; PRTSY
;---------------------------------------------------------------
;! Task to print statistics from the SY table
;# TASK EXT-APPL CALIBRATION VLA
;-----------------------------------------------------------------------
;;  Copyright (C) 2012, 2014, 2016, 2018
;;  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
;-----------------------------------------------------------------------
PRTSY     LLLLLLLLLLLLUUUUUUUUUUUU CCCCCCCCCCCCCCCCCCCCCCCCCCCCC
PRTSY:  Task to print SY table statistics
INNAME                             Image name(name).
INCLASS                            Image name(class).
INSEQ           0.0      9999.0    Image name(seq. #). 0=>high
INDISK                             Disk drive #. 0=>any
INVERS          0.0     46655.0    SY table version number
SOURCES                            Source names to include
QUAL            -10.0              Qualifier -1=>all
CALCODE                            Restrict to this calcode
SELBAND                            Bandwidth to select (kHz)
SELFREQ                            Frequency to select (MHz)
FREQID                             Freq. ID to select.
SUBARRAY          0.0     1000.0   Subarray, 0 => 1
TIMERANG                           Time range to use
FLAGVER          -1.0              > 0 => apply flags to SY
DOCRT            -3.0     132.0    > 0 -> use the terminal,
                                   else use the line printer
                                   > 72 => terminal width
OUTPRINT                           Printer disk file to save
OPTYPE                             'DIFS','SUMS','TSYS' list
                                   simple stats of this type
                                   ' ' -> all 3 above
                                   'DRMS', 'SRMS', 'TRMS'
                                   'RMS ' => all 3 rms's
OPCODE                             'SCAN' list by antenna and
                                      scan one IF at a time
                                   'IFS ' list by IF and scan
                                      one antenna at a time
                                   'ANTS' list by IF and
                                      antenna one scan at a time
                                   'SORC' list by IF and
                                      antenna a source at a time
                                   'EFFS' list by IF and
                                      antenna a source at a time
                                      also write efficiencies
                                   else statistical not median
DPARM                              (1) scale Pdiff or Pdiff rms
                                   (2) scale Psum or Psum rms
                                   (3) scale Psys or Psys rms
                                   (4) Ratio wrt IF DPARM(4)
                                   (5) Ratio wrt ant. DPARM(5)
                                   (6) Ratio wrt scan DPARM(6)
                                   (7) Ratio wrt source DPARM(7)
                                       (actual source number)
CALIN                              Antenna efficiencies file
                                      'EFFS' only
OUTFILE                            New efficiencies
                                      'EFFS' only
BADDISK                            Disks to avoid for scratch
----------------------------------------------------------------
PRTSY
Type: Task
Use:  PRTSY reads EVLA SY and CD tables and computes statistics of the
      Pdif, Psum, and Tsys values found on a per IF, per antenna, per
      scan or source basis.
Adverbs:
  INNAME.....Image name (name).       Standard defaults.
  INCLASS....Image name (class).      Standard defaults.
  INSEQ......Image name (seq. #).     0 => highest.
  INDISK.....Disk unit #.             0 => any.
  INVERS.....Version number of SY table to be examined.
  SOURCES....List of sources to be printed. '  '=> all; if any
             starts with a '-' then all except ANY source named.
  QUAL.......Qualifier of source to be printed.    -1 => all.
  CALCODE....Calibrator code of sources to print.  ' '=> all.
                  '*   ' => any non blank code (cal. only)
                  '-CAL' => blank codes only (no calibrators)
                  anything else = calibrator code to select.
  SELBAND....Bandwidth of data to be selected. If more than one IF is
             present SELBAND is the width of the first IF required.
             Units = kHz. For data which contain multiple
             bandwidths/frequencies the task will insist that some form
             of selection be made by frequency or bandwidth.
  SELFREQ....Frequency of data to be selected. If more than one IF is
             present SELFREQ is the frequency of the first IF required.
             Units = MHz.
  FREQID.....Frequency identifier to select (you may determine which is
             applicable from the OPTYPE='SCAN' listing produced by
             LISTR). If either SELBAND or SELFREQ are set, their values
             overide that of FREQID.  However, setting SELBAND and
             SELFREQ may result in an ambiguity.  In that case, the task
             will request that you use FREQID.  If all SELBAND, SELFREQ
             and FREQID are not specified (.le. 0) then all FQ ids will
             be selected.
  SUBARRAY...Subarray number to print.       0 => 1.
  TIMERANG...Time range of the data to be plotted. In order:
             Start day, hour, min. sec, end day, hour, min. sec.
             Days relative to reference date.
  FLAGVER....> 0 => apply flag table version FLAGVER to SY table
  DOCRT......False (<= 0) use the line printer if OUTPRINT = ' '
                 else write named OUTPRINT file only.
                 When OUTPRINT is not blank, DOCRT=-2 suppresses the
                 page-feed character on page headers and DOCRT=-3
                 suppresses page headers and most other header
                 information.  When OUTPRINT is blank, the line
                 printer will be used.  PRTSY now counts the lines
                 to be printed before printing any and asks for
                 permission to continue if the count > 500.
             True  (> 0) use the terminal interactively.  The task
                 will use the actual terminal width as a display limit
                 unless 72 < DOCRT < width.  In that case, the display
                 limit will be DOCRT characters.
  OUTPRINT...Disk file name in which to save the line printer output.
             ' ' => use scratch and print immediately for interactive
             jobs - batch jobs use OUTPRINT = 'PRTFIL:BATCHjjj.nnn'
             (jjj= job #, nnn = user #).  When OUTPRINT is not blank,
             multiple outputs are concatenated, and the file is not
             actually printed.
  OPTYPE.....'DIFS' print only Pdif information
             'SUMS' print only Psum information
             'TSYS' print only Tcal*Psum/Pdif information
             ' '    print all 3 of above
             'DRMS' print rms of Pdif from median computations
             'SRMS' print rms of Psum from median computations
             'TRMS' print rms of Tcal*Psum/Pdif from median
                    computations
             'RMS ' print all 3 of the median computation RMSes
  OPCODE.....'SCAN' do median scan averages, then print one IF at a
                    time with antennas across the page and scan down
                    the page
             'IFS ' do median scan averages, then print one antenna at
                    a time with IFs across the page and scan down the
                    page
             'ANTS' do median scan averages, then print one scan at a
                    time with IFs across the page and antennas down
                    the page
             'SORC' do median source averages, then print one scan at
                    a time with IFS across the page and antennas down
                    the page
             'EFFS' do 'SORC' above but then change input efficiencies
                    into those implied by the PSUMs of the current
                    data.  In this case, only 2 sources should be
                    specified, one of which is also in DPARM(7) as a
                    reference.  One antenna in DPARM(5) must also be
                    specified.
             other  do non-robust averaging across the selected data
                    and print all sorts of statistical information
  DPARM......The median displays ('SCAN', 'IFS ') print normalized
             values but the normalization may be seriously affected by
             a few high values.  You may scale those displays by a
             factor (0 -> 1, values > 1 are useful).
             (1) Scale Pdif values in the robust average displays
             (2) Scale Psum values in the robust average displays
             (3) Scale Psys values in the robust average displays
             (4) Display ratio with value in IF = DPARM(4),
                 0 -> no ratio wrt IF
             (5) Display ratio with value in antenna = DPARM(5),
                 0 -> no ratio wrt antenna
             (6) Display ratio with value in scan = DPARM(6),
                 0 -> no ratio wrt scan.
                 Option used with SCAN, IFS, ANTS only
             (7) Display ratio with values in source = DPARM(7)
                 0 -> no ratio wrt source
                 Option used with SORC only
  CALIN......The name of a text file to provide antenna efficiencies
             as a function of antenna, frequency, and polarization.
             By default, the system file is called:
                 'AIPSIONS:VLA.EFFICIENCIES'
             If it is missing, a small table which is antenna and
             polarization independent is used instead.
  OUTFILE....Efficiency file for current data
  BADDISK....The disk numbers to avoid for scratch files (sorting
             tables mostly).
----------------------------------------------------------------

Some details:

If OPCODE is not 'SCAN', 'IFS', 'ANTS', 'SORC', or 'EFFS'
==========================================================

PRTSY reads through the SY table selecting all records which match the
TIMERANG, SOURCES, SUBARRAY, and FREQID adverbs.  For those records
which are not blanked and not obviously invalid, it computes
               Tsys = Tcal * Psum / (2 * Pdif)
and then finds the mean, rms, maximum, and minimum of Pdif, Psum, and
Tsys separately for each IF and antenna.  Then it prints the
statistics for Pdif followed by those for Psum, followed by those for
Tsys.  You control which one (or all) of these is printed with OPTYPE.
The display prints a line for each antenna and IF, with IF changing
faster, containing columns for antenna, IF, RR average, rms, minimum,
maximum, and count, followed by similar columns for LL.  Values are
left blank in the display for antennas or IFs having no valid data.
Then there is a display of the same columns for each antenna, averaged
over IF.  And finally, there is a line of the same columns, averaged
over antenna and IF.  The DPARM adverb is not used in this mode which
is good for identifying problem IFs and antennas.  The values
displayed are, however, often skewed significantly by bad SY table
values.


If OPCODE is 'SCAN', 'IFS', or 'ANTS'
=====================================

PRTSY reads through the SY table selecting all records which match the
TIMERANG, SOURCES, SUBARRAY, and FREQID adverbs.  It then saves the
matching Pdif and Psum in memory and also saves the index table data
in memory.  Using the latter to define scans, PRTSY then finds the
median Pdif, Psum, and Tsys on a polarization, IF, antenna, and scan
basis.  It also computes an rms deviation from these medians.  If
normalizations are requested, it normalizes the medians and rmses by
the requested medians.

PRTSY then displays the results selecting which results to display
depending on OPTYPE.  Pdif is displayed on 'DIFS' and ' ', Psum is
displayed on 'SUMS' and ' ', Tsys is displayed on 'TSYS" and ' ',
the rms of Pdif is displayed on 'DRMS' and 'RMS ', the rms of Psum is
displayed on 'SRMS' and 'RMS ', and the rms of Tsys is displayed on
'TRMS' and 'RMS '.

   Then if OPCODE is 'SCAN'
   ========================

   For RR polarization, PRTSY displays one IF at a time, starting a
   new page for each IF.  It then repeats the operation for LL
   polarization.  The display consists of one line per scan showing
   the time, source name, and scaled parameter value for as many
   antennas as will fit across the page.  It will loop if needed to do
   all antennas.  Blanked or missing values are shown as ' ---'.

   Then if OPCODE is 'IFS'
   ========================

   For RR polarization, PRTSY displays one antenna at a time, starting
   a new page for each antenna.  It then repeats the operation for LL
   polarization.  The display consists of one line per scan showing
   the time, source name, and scaled parameter value for as many IFs
   as will fit across the page.  It will loop if needed to do all IFs.
   Blanked or missing values are shown as ' ---'.

   Then if OPCODE is 'ANTS'
   ========================

   For RR polarization, PRTSY displays one scan at a time, starting a
   new page for each scan.  It then repeats the operation for LL
   polarization.  The display consists of one line per antenna showing
   the antenna number and scaled parameter value for as many IFs as
   will fit across the page.  It will loop if needed to do all IFs.
   Blanked or missing values are shown as ' ---'.


If OPCODE is 'SORC' or 'EFFS'
=====================================

PRTSY reads through the SY table selecting all records which match the
TIMERANG, SOURCES, SUBARRAY, and FREQID adverbs.  It then saves the
matching Pdif and Psum in memory.  PRTSY then finds the median Pdif,
Psum, and Tsys on a polarization, IF, antenna, and source basis.  It
also computes an rms deviation from these medians.  If normalizations
are requested, it normalizes the medians and rmses by the requested
medians.

PRTSY then displays the results selecting which results to display
depending on OPTYPE.  Pdif is displayed on 'DIFS' and ' ', Psum is
displayed on 'SUMS' and ' ', Tsys is displayed on 'TSYS" and ' ',
the rms of Pdif is displayed on 'DRMS' and 'RMS ', the rms of Psum is
displayed on 'SRMS' and 'RMS ', and the rms of Tsys is displayed on
'TRMS' and 'RMS '.

Then, for RR polarization, PRTSY displays one source at a time,
starting a new page for each source.  It then repeats the operation
for LL polarization.  The display consists of one line per antenna
showing the antenna number and scaled parameter value for as many IFs
as will fit across the page.  It will loop if needed to do all IFs.
Blanked or missing values are shown as ' ---'.

If OPCODE='EFFS', the task then finds the efficiencies current used
for the present spectral window (IF) frequencies for the reference
antenna.  It then uses the Psum (on strong source) / Psum (off strong
source) relative to the same ratio on the reference antenna to make
a new table of effiiencies by antenna, IF, and polarization.  If p is
polarization, I is IF, A is antenna, R is the refernce antenna, and
source M is the strong source (e.g. Cygnus A) and N is the weak (or
off) source, then the output efficiencies are:
                              Psum(p,I,A,M) Psum(p,i,R,N)
    Eff(p,I,A) = Eff(p,I,R) * ------------- -------------
                              Psum(p,I,A,N) Psum(p,I,R,M)
