; TARPL
;---------------------------------------------------------------
;! Plot output of TARS task
;# TASK PLOT ANALYSIS POLARIZATION
;-----------------------------------------------------------------------
;;  Copyright (C) 2012, 2014
;;  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
;-----------------------------------------------------------------------
TARPL     LLLLLLLLLLLLUUUUUUUUUUUU CCCCCCCCCCCCCCCCCCCCCCCCCCCCC
TARPL:  Task to generate a plot file from TARS output text file
USERID     -32000.0     32000.0    User ID - ignored
INNAME                             Image name(name).
INCLASS                            Image name(class).
INSEQ           0.0      9999.0    Image name(seq. #). 0=>high
INDISK          0.0         9.0    Disk drive #. 0=>any
INTEXT
                                   Text file with plot info
APARM                              Controls over plot
                                   (1,2) X value range
                                   (3,4) Y amp/real value range
                                   (5,6) Y ph/imag value range
                                   (7) > 0 -> real,imag plot
                                       also see HELP
RPARM                              (1-30) Symbol types (0->24)
VPARM                              (1-30) Line types (0->..)
FACTOR                             Scale symbol sizes
DO3COL         -1.0         2.0    > 0 use multi-color plots
LTYPE        -410.0       410.0    Type of labeling: 1 border,
                                   2 no ticks, 3 standard, 4 rel
                                   to center, 5 rel to subim cen
                                   6 pixels, 7-10 as 3-6 with
                                   only tick labels
                                   <0 -> no date/time
XYRATIO         0.0                XYratio scale plot
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.
----------------------------------------------------------------
TARPL
Type: Task
Use:  TARPL will write commands to a plot file for the execution
      of a ????? plot for a TARS output file.  Up to 30 RM spectra
      from may be in the input text file, each of which may be plotted
      with a selected plot symbol (or omitted).  They may be connected
      by lines as well.
Adverbs:
  USERID......The ID of the owner of the image.  Ignored
  INNAME......Image name (name).       Standard defaults.  The plot file
              is attached to this AIPS file which is otherwise ignored.
  INCLASS.....Image name (class).      Standard defaults.
  INSEQ.......Image name (seq. #).     0 => highest.
  INDISK......Disk unit #.             0 => any.
  INTEXT......Text file containing data from TARS (see explain for
              details)
  APARM.......(1,2) X plot range.  If APARM(2) <= APARM(1), self scale.
              (3,4) Y plot range for amplitude/real.  If APARM(4) <=
                    APARM(3), self scale.
              (5,6) Y plot range for phase/imaginary.  If APARM(6) <=
                    APARM(5), self scale.
              (7)   =  1 => Plot real and imaginary
                    =  2 => Plot real
                    =  3 => Plot imaginary
                    = -1 => Plot amplitude and phase
                    = -2 => Plot amplitude
                    = -3 => Plot phase
                    = 0  -> -1
  RPARM.......(1-30) Plot symbol number for data of group 1-30, resp.
              You may have both a symbol and a line for each group
              0: No symbol plotted for this type
              1: Plus sign             12: Five pointed star
              2: Cross (X)             13: Star of David
              3: Circle                14: Seven-pointed star
              4: Box                   15: Eight-pointed star
              5: Triangle              16: Nine-pointed star
              6: Diamond               17: Ten-pointed star
              7: Pentagon              18: 11-pointed star
              8: Hexagon               19: 12-pointed star
              9: Septagon              20: 13-pointed star
              10: Octagon              21: 14-pointed star
              11: Nine-gon             22: Plus with gap
                                       23: Vertical line
                                       24: Cross (X) with gap
              If RPARM(i) is < 0, use abs (RPARM(i)) for phase only.
  VPARM.......(1-30) Line type number for data of group 1-30, resp.
              You may have both a symbol and a line for each group
              0: No line plotted for this group
              1: connected solid step line
              2: connected solid line
              3: dashed line, 1 break between points
              4: dashed line, 2 breaks between points
              5: and so on (VPARM(I)-2 breaks between points)
              If VPARM(i) is < 0, use abs (VPARM(i)) for all plots
              except phase.
  FACTOR......Symbol size multiplier; 0 -> 1.
  DO3COL......> 0 plot with colors (up to 4 groups use graphics planes
                  4, 3, 2, 1, > 4 groups use true grey-scale colors)
              = 2 plot with true grey-scale colors even with <= 4
                  groups
              <=0 plot without colors
  LTYPE.......Labelling type, see HELP LTYPE for details:
              1 = border, 2 = no ticks, 3 or 7 = standard, 4 or 8 =
              relative to ref. pixel, 5 or 9 = relative to subimage
              (BLC, TRC) center, 6 or 10 = pixels.  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.
              Add n * 100 to alter the metric scaling.
  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.
----------------------------------------------------------------
TARPL: Task to create a TARPL-plot extension file
DOCUMENTOR:
RELATED PROGRAMS: TKPL, TVPL, LWPLA, PLOTR

                           PURPOSE

     TARPL generates a plot extension file containing a TARPL plot,
its border, and labels.  The plot itself may be displayed on a
printer, TEK screen, or TV graphics channel by the tasks PRTPL, TKPL,
or TVPL respectively.

                          COMMENTS

Each data group begins with a line starting with ';   K' with the next
line giving a value of K equal 1.  The beginning line also gives
scaling and type information.  The task reads the data for the first
group until the end of file or another group start card is found.
then it reads the data for group 2 and so forth.  Which groups are
plotted is determined by RPARM and VPARM.

There may be 30 groups each of <= 2000 values.

The text file can contain other comment cards starting with an
character not blank or a number so long as they do not start with
semi-colon, 3 blanks, and the letter K (';   K').

An example file (with ... being large numbers of skipped lines):

; Un-cleaned spectrum
;   K        RM      10^6 AMP       PHASE
    1     -2400.0    18044.50      111.00
    2     -2390.0    19425.98      101.09
    3     -2380.0    19881.87       86.20
    4     -2370.0    18669.91       73.99
    5     -2360.0    18466.89       66.94
    6     -2350.0    19887.04       56.34
...
  476      2350.0    20757.54       55.94
  477      2360.0    19309.42       43.72
  478      2370.0    18931.11       36.74
  479      2380.0    20227.05       26.16
  480      2390.0    20286.32       11.16
  481      2400.0    18806.63       -0.35
============================================
;  point clean, niter=40
;   K        RM      10^6 AMP       PHASE
    1     -2400.0     9577.88      100.81
    2     -2390.0    10277.84       91.69
    3     -2380.0    10651.21       76.99
    4     -2370.0    10047.17       64.06
    5     -2360.0     9808.13       56.79
    6     -2350.0    10542.97       46.88
...
  476      2350.0    11758.80       46.39
  477      2360.0    11008.49       33.45
  478      2370.0    10645.12       26.11
  479      2380.0    11326.65       16.28
  480      2390.0    11490.52        1.47
  481      2400.0    10687.82      -10.73
------------------------------------------
;  restored Clean, niter = 40
;   K        RM      10^6 AMP       PHASE
    1     -2400.0     3059.55      100.78
    2     -2390.0     3280.26       91.73
    3     -2380.0     3405.67       77.16
    4     -2370.0     3229.52       64.22
    5     -2360.0     3162.23       56.55
    6     -2350.0     3382.37       46.33
...
  476      2350.0     3720.13       46.79
  477      2360.0     3497.08       33.65
  478      2370.0     3379.61       26.01
  479      2380.0     3578.18       16.07
  480      2390.0     3615.54        1.41
  481      2400.0     3361.39      -10.51
------------------------------------------
;  restored Clean, niter = 40, real and imag
;   K        RM       10^6 RE     10^6 IM
    1     -2400.0     -322.27     1699.33
    2     -2390.0      -57.49     1852.45
    3     -2380.0      422.54     1881.74
    4     -2370.0      795.59     1657.96
    5     -2360.0     1002.64     1502.52
    6     -2350.0     1342.41     1376.20
...
  476      2350.0     1417.02     1525.49
  477      2360.0     1634.68     1091.80
  478      2370.0     1709.40      824.63
  479      2380.0     1924.21      541.16
  480      2390.0     2010.37       42.11
  481      2400.0     1836.94     -337.48
