; PCEDT
;---------------------------------------------------------------
;! Interactive TV task to edit pulse-cal (PC) tables
;# TASK UV CALIBRATION EDITING TV-APPL INTERACTIVE OOP VLBI
;-----------------------------------------------------------------------
;;  Copyright (C) 2016-2018, 2020
;;  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
;-----------------------------------------------------------------------
PCEDT     LLLLLLLLLLLLUUUUUUUUUUUU CCCCCCCCCCCCCCCCCCCCCCCCCCCCC
PCEDT:  PC-table graphical editor
INNAME                             Input UV data (name)
INCLASS                            Input UV data (class)
INSEQ                              Input UV data (seq. #)
INDISK                             Input UV data disk drive #
INVERS                             Input table file version no.
FREQID           -1.0              Frequency ID; 0 => 1
SUBARRAY          0.0              Subarray number 0 => 1.
TIMERANG                           Time range to include
BIF                                First IF to include
EIF                                Last IF to include
ANTENNAS                           Antennas to include/exclude
DOHIST          -10.0       1.0    Record flags in history file
CROWDED          -1.0       2.0    = 1 => allow plots with all
                                          times
                                   = 2 => use memory grid to
                                          do plots
DO3COLOR         -1.0       2.0    > 0 => do CROWDED with
                                          multiple colors
                                   = 2 => always use colors
ANTUSE            0.0      90.0    Initial displayed antennas
APARM                              Initial plot ranges for
                                   (1,2) amplitude
                                   (3,4) phase
                                   (5,6) residual phase
BADDISK                            Disks to avoid for scratch
----------------------------------------------------------------
PCEDT
Type:  Task
Use:   To edit PC-table data by examining the PC table spectra.
       The chosen observable, i.e,. amplitudes, phases, or residual
       phases (after a fit delay and phase are subtracted) for an
       antenna is displayed as a function of spectral channel in an
       edit window.  You may view the entire channel range or select
       more detailed channel ranges interactively.  A second
       observable for the same antenna is displayed over the same
       channel range in a window above the edit window.  Data in the
       primary observable for 0 to 10 other antennas may be displayed
       over the same channel range in windows above these on the TV
       screen.  This display is controlled interactively.  A menu-like
       control interface is available to select the antenna and time
       range to be edited and to select various forms of editing.

       PCEDT creates a Flag Command file attached to the input UV data
       file.  If one already exists - due to a prior power failure or
       program failure - it will be used.  This is a bit dangerous and
       should be done only if the data selection adverbs have the values
       they had when the FC file was created.
Adverbs:
  INNAME.....Input UV data file (name).       Standard defaults.
  INCLASS....Input UV data file (class).      Standard defaults.
  INSEQ......Input UV data file (seq. #).     0 => highest.
  INDISK.....Input UV data file disk drive #. 0 => any.
  INVERS.....Input table file version number, 0 -> current highest.
             The input file is copied and sorted to a new version.  If
             flags are actually prepared, the new version is changed
             to reflect the flagging and kept; otherwise it is
             deleted.
  FREQID.....Frequency ID to edit.  0 => 1.
  SUBARRAY...Subarray number to edit.  0 => 1.
  TIMERANG...Time range of the data to be edited. In order:
             Start day, hour, min. sec, end day, hour, min. sec. Days
             are relative to the reference date.
  BIF........The lowest numbered IF to include.   0 => 1.
  EIF........The highest numbered IF to include. 0 =>highest.
             Note: not all data sets will have IFs.
  ANTENNAS...A list of antenna numbers to include.  0 => all.
  DOHIST.....> 0 => record task execution and flagging info in the
             history file (this can be a lot!).  <= 0.0 means to omit
             the flagging info and <= -9.5 means to omit the execution
             information as well.
  CROWDED....If = 1, the task will be allowed to plot and edit all times
             at once.  Otherwise, only one time for the chosen antenna
             is displayed and edited.
             If = 2, the plots will be constructed in dynamic memory
             and then loaded as images rather than being drawn directly
             to the TV.  Use this if there are a lot of times being
             over-plotted to save time.
  DO3COLOR...If CROWDED > 0 and DO3COL > 0, use 3 grey-scale image
             planes to plot the data in colors so as to differentiate
             between times.  The first time is pure red, the last
             nearly pure blue.  Blue can overwrite the earlier times.
             DO3COL > 1.5 tells the task to use the color of the time
             always.  Otherwise, graphics plane 1 (yellow) is used
             when only one time is displayed.
  ANTUSE.....Lists the antennas to appear in the initial display:
             antenna ANTUSE(1) is the initial edit antenna and
             ANTUSE(2) through ANTUSE(11) are the comparison antennas.
             The default is equivalent to ANTUSE=1,2,3 (or whatever
             are the 3 lowest numbered antennas).
  APARM......Initial plot rnges - can change later
             (1) Minimum amplitude plotted
             (2) Maximum amplitude plotted  (1) >= (2) self-scale
             (3) Minimum phase (degrees) plotted
             (4) Maximum phase plotted   (3) >= (4) self-scale
             (5) Minimum residual phase (degrees) plotted
             (6) Maximum residual phase plotted   (5) >= (6) self-scale
  BADDISK....The disk numbers to avoid for scratch files (sorting
             tables mostly).
------------------------------------------------------------------------

     PCEDT is a TV graphic editor for PC-table data using the data of
the table.  It works with the XAS-TV display graphics (and image)
planes to allow you to flag the table data based on values in the
selected table.

     PCEDT attempts to read the entire table into dynamic memory when
it starts up.  If it cannot fit all the data, it attempts to read just
one IF at a time.  In that case, when you switch IFs, PCEDT reads in
the next IF.  PCEDT will tell you as it starts whether "All data will
reside in memory" or "Will do only one IF in memory at a time".  The
SWITCH ALL IF option will not appear in the latter case.

     There are 5 parts to PCEDT's display:
(1) A menu of operations displayed in two columns, one each at the left
and right sides of the screen.  When the menu is displayed, move the
cursor to the desired item and press buttons A, B, or C.  To get on-line
help in the message window about a given option, move the cursor to the
desired menu item and press button D.
(2) A plot at the bottom of the screen in a bright color (usually) of
the data which may be actively edited at present.  It is of the chosen
type for the selected antenna, polarization(s), and IF(s).  Flagged
data are shown in a different color.  The frequecy range of the frame
may be made small to expand the frequency axis, but may also be made
so large as to cause serious crowding of the plotted data points.
(Increase your XAS window width to increase the plot scale.)
(3) A plot above the edit area plot in the same bright color of the data
from the selected antenna, polarization(s), and IF(s).  This plot is
in a second observable (e.g. if amplitude is in the edit plot, phase
is the second observable).  Data in this second area may not be used
for editing but should be helpful in choosing which data to delete in
the edit area.  Flagged data are shown in a different color.  This
plot may be suppressed by adverb DOTWO.
(4) 0-10 plots of data of the current data type, polarization(s), and
IF(s) for a list of 0-10 other antennas are shown above the second
plot.  They are shown for comparison using another color, while
flagged data are shown in a different color.
(5) Several text areas also appear including (a) the IF numbers in the
current frame's frequency axis, (b) the selected data type, IF, and
polarization at the bottom of the screen, (c) the antenna shown in each
plot at the top right of each plot, (d) the current time and all-IF,
all-polarization, and all-antenna flags, (e) the y-axis tick values on
each of the frame plots, and (f) while interactively setting channel
and/or value ranges, the channel/IF and value to which you are
currently pointing and the associated source name.

     You may change the size of the XAS window at any time.  PCEDT will
not allow it to become too small, but will adjust its display for all
reasonable sizes.

     The left-hand menu can contain
-------------------
| FLAG CHANNEL    |  To delete one channel at a time.
| FLAG CHAN RANGE |  To delete one or more channel ranges.
| FLAG BELOW      |  To delete all displayed times with data below a
                        cutoff value.
| FLAG ABOVE      |  To delete all displayed times with data above a
                        cutoff value.
| FLAG AREA       |  To delete one or more areas in the data-value -
                        time plane.
| FLAG POINT      |  To delete one sample at a time using both
                        horizontal and vertical cursor position.
| FLAG QUICKLY    |  To delete samples using only mouse clicks
| ENTER AMPL RNG  |  To select the display range for amplitude plots.
                        Use 0 -1 for 0 to antenna maximum and 0 0 for
                        min to max.
| ENTER PHASE RNG |  To select the display range for phase plots.
| ENTER RESID RNG |  To select the display range for RESIDUAL phase
                        plots.
| LIST FLAGS      |  To list all flags now in the Flag Command table.
| UNDO FLAGS      |  To undo one of the flag operations in the FC table
| REDO FLAGS      |  To reapply all remaining flags after one or more
                        have been undone (see note below)
| REDO DELAYS     |  To solve for delay and phase to compute the
                        residuals taking into account current flagging
| TV ZOOM         |  To alter the display zoom used while in the flag
                        functions.
| OFF ZOOM        |  To turn off any zooming.
| HOLD TV LOAD    |  To stop updating the TV display with every change
                        of parameter; change several, then select
| DO TV LOAD      |  To update the TV display now and with each change
                        of display parameter.
| REPLOT          |  To do the current plot over again, recomputing
                        the differences from the running mean if
                        appropriate.
| EXIT            |  To exit PCEDT, writing the flagging information
                        in the output flag table.
| ABORT           |  To exit PCEDT, deleting the the FC table
-------------------

     The right-hand menu can contain
-------------------
| SWITCH POLARIZ  |  To switch to viewing and editing the other
                        polarization (can cycle through all).
| SWITCH ALL POL  |  To switch functions from applying to one
                        polarization to applying to both polarizations
                        or vice versa.
| SWITCH ALL TIME |  To switch FLAG ABOVE and FLAG BELOW between all
                        times and the time range of the frame
| SWITCH ALL SOURC|  To switch between flagging the current source and
                        all sources.
| SWITCH ALL ANT  |  To switch functions from applying to one antenna to
                        applying to all antennas or vice versa.
| ENTER ANTENNA   |  To select the antenna to be displayed at the top
                        and in the edit area and to be edited.
| ENTER OTHER ANT |  To select up to 10 other antennas to be displayed;
                        enter only the ones you want including none
| NEXT ANTENNA    |  To select an antenna one higher than the currently
                        selected antenna
| PLOT ALL CHANNEL|  To display and edit data for all channels.
| SELECT FRAME    |  To select a window into the current data
                        interactively.
| NEXT FRAME      |  To select the next channel range window.
| PREVIOUS FRAME  |  To select the previous channel range window.
| SELECT IF       |  To select a single IF to display and edit by
                        typing its number into the terminal window
| NEXT IF         |  To select the next higher IF to display and edit
| LAST IF         |  To select the next lower IF to display and edit
| NEXT TIME       |  To select the next higher time to display and
                        edit
| LAST TIME       |  To select the next lower time to display and
                        edit
| SHOW AMPLITUDE  |  To display and edit using amplitudes
| SHOW PHASE      |  To display and edit using phases.
| SHOW RESID      |  To display and edit using residual phases.
| SHOW ALSO AMP   |  To display amplitudes in the second plot area
| SHOW ALSO PHASE |  To display phases in the second plot area
| SHOW ALSO RESID |  To display residual phases in the second plot area
-------------------

     The menus will not show all of these options every time.  The HOLD
TV LOAD option is shown until invoked, and then is replaced with the DO
TV LOAD.  When that is invoked, the HOLD TV LOAD option reappears.  The
SWITCH POLARIZ and SWITCH ALL POL options appear only if there are two
polarizations in the BP table.  The only SHOW options to appear are
for those not already displayed.  The SHOW xxx and SHOW ALSO xxx items
appear as appropriate.

     The pulse-cal spectra are fit for delay and phase when the PC
table is read and residual spectra are computed.  They are not
automatically recomputed when data are flagged.  You can request the
task to recompute the residuals at any time -- do it after flagging
some bad data.

     Note that value-dependent flagging (FLAG BELOW, ABOVE, AREA) uses
the values currently plotted to make a list of value-independent flag
commands (i.e., a single channel and time for the specified antennas,
IFs, polarizations, etc.).  When a value-dependent FLAG operation is
undone (UNDO FLAGS) or redone (REDO FLAGS), it is these
value-independent flags which are undone or redone.  You may have to
undo more commands and then repeat FLAG commands to get the results
you could have gotten by doing the now desired value-dependent command
in the first place.  You need also to be careful with the SWITCH ALL
ANT setting with these value-dependent commands.  If one antenna is
set, then the commands only apply to the current antenna.  If all
antennas is set, the commands apply to all antennas.  The first two
set a clip level, below or above which data are deleted, based on the
value of the observable in each antenna independently.  The FLAG AREA
command, however, only looks at the values of the observable in the
main edit antenna and flags those samples from all applicable
antennas.

     Be careful when choosing EXIT versus ABORT.  The former applies the
flag commands to the output PC table attached to the input uv data,
the latter causes the flag commands and the output PC table to
disappear without a trace.

     The colors used by PCEDT are those of the various graphics planes
when it begins to run.  You may change them with the AIPS verb GWRITE to
more desirable colors.  The planes are:
   Plane     Default RGB      Use
     1     1.00  1.00  0.00   Main editing and secondary windows
     2     0.06  1.00  0.00   Comparison antenna data windows
     3     1.00  0.67  1.00   Menu highlight
     4     0.00  1.00  1.00   Edit and frame window boundaries
     5     1.00  0.18  0.18   Flagged data in all windows
     6     0.60  0.60  1.00   Menu foreground
     7     1.00  0.80  0.40   unused
You may wish to change the colors to ones that you can see better.
------------------------------------------------------------------------
