; WIPER
;---------------------------------------------------------------
;! plots and edits data from a UV data base using the TV
;# Task UV Plot Editing interactive TV-APPL
;-----------------------------------------------------------------------
;;  Copyright (C) 2002-2004, 2006-2010
;;  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
;-----------------------------------------------------------------------
WIPER     LLLLLLLLLLLLUUUUUUUUUUUU CCCCCCCCCCCCCCCCCCCCCCCCCCCCC
WIPER     Plots and edits data from a u,v data base using TV
INNAME                             Input UV file name (name)
INCLASS                            Input UV file name (class)
INSEQ             0.0     9999.0   Input UV file name (seq. #)
INDISK                             Input UV file disk unit #
SOURCES                            Sources to plot, ' '=>all.
QUAL            -10.0              Qualifier -1=>all
CALCODE                            Calibrator code '    '=>all
STOKES                             Stokes type to select.
SELBAND                            Bandwidth to select (kHz)
SELFREQ                            Frequency to select (MHz)
FREQID                             Freq. ID to select.
TIMERANG                           Time range to select
ANTENNAS                           Antennas to plot
BASELINE                           Baselines with ANTENNAS
UVRANGE                            UV range in kilolambda.
SUBARRAY          0.0     1000.0   Subarray, 0 => all
BCHAN             0.0     4096.0   1st spectral channel #
ECHAN             0.0     4096.0   Last spectral channel #
NCHAV             0.0     4096.0   # of channels to average
CHINC             0.0     4096.0   Increment in channel #
BIF                                Low IF number to plot
EIF                                Highest IF number to plot
DOCALIB          -1.0      101.0   > 0 calibrate data & weights
                                   > 99 do NOT calibrate weights
GAINUSE                            CAL (CL or SN) table to apply
DOPOL            -1.0       10.0   If >0 correct polarization.
PDVER                              PD table to apply (DOPOL>0)
BLVER                              BL table to apply.
FLAGVER                            Flag table version
OUTFGVER          0.0              Output FG table version
DOBAND           -1.0       10.0   If >0 apply bandpass cal.
                                   Method used depends on value
                                   of DOBAND (see HELP file).
BPVER                              Bandpass table version
SMOOTH                             Smoothing function. See
                                   HELP SMOOTH for details.
BPARM                              Control parameters
                                   1 : X-axis type 0=>UV dist
                                   2 : Y-axis type 0=>Ampl
                                       1=> amplitude (Jy)
                                       2=> phase (degrees)
                                       3=> uv dist. (klambda)
                                       4=> uv p.a. (deg N->E)
                                       5=> time (IAT days)
                                       6=> u (klambda)
                                       7=> v (klambda)
                                       8=> w (klambda)
                                       9=> Re(Vis) (Jy)
                                       10=> Im(Vis) (Jy)
                                       11=> time (IAT hours)
                                       12=> log(ampl)
                                       13=> weight
                                       14=> HA (hours)
                                       15=> elevation (deg)
                                       16=> parallactic angle
                                       17=> uv dist. (klambda)
                                            along p.a.
                                       18=> azimuth (deg)
                                   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 : radius of fat wiper
                                   10: > 0 => plot auto-corr too
REFANT          0.0        90.0    > 0 => use REFANT for plot
                                   types 14, 15, 16
ROTATE       -360.0       360.0    uv p.a. for projection
                                   (deg N->E); type 17 only
IMSIZE          0.0      9999.0    Size of plot in memory
DOCENTER        -1.0        1.0    Place menu at left (-1),
                                   center (1), right (0)
DOALL          -1.0         7.0    bit 1 flag all channels
                                   bit 2 flag all IFs if 1
                                   bit 3 flag all polarizations
BADDISK                            Disk to avoid for scratch.
----------------------------------------------------------------
WIPER
Type: Task
Use:  Plots data from a u,v data base, with calibration if desired, in
      the manner of UVPLT, putting the plot into an array in memory.
      This array is then displayed in whole, or in part, on the TV and
      various interactive editing options are available.  The pixels
      in the plot are, at the end, converted into flags in a new flag
      table.  Lines one pixel outside the plot, surrounding it, and
      lines at x and y value 0.0 are drawn when possible.  The plots
      are labeled when either the full image or a sub-image is
      plotted.

      During interactive editing, the image pixel coordinates, the X
      and Y physical coordinates, the number of samples contributing
      to the pixel, and up to two baselines contributing to the pixel
      are plotted for the pixels selected by the TV cursor.
Adverbs:
  INNAME.....Input UV file name (name)    Standard defaults.
  INCLASS....Input UV file name (class)   Standard defaults.
  INSEQ......Input UV file name (seq. #)  0 => highest.
  INDISK.....Disk drive # of input UV file.  0 => any.
  SOURCES....List of sources to be plotted. '  '=> all; if any starts
             with a '-' then all except ANY source named.
  QUAL.......Qualifier of source to be plotted. -1 => all.
  CALCODE....Calibrator code of sources to plot. ' '=> all.
  STOKES.....The desired Stokes type of the plotted data:
               'I','Q','U','V', 'IV', 'IQU', 'IQUV'
               'RR','LL', 'RL', 'LR', 'RRLL', 'RLLR', 'RLRL'
               'XX','YY', 'XY', 'YX', 'XXYY', 'XYYX', 'XYXY'
             'HALF', 'CROS', and 'FULL' have sensible interpretations
             depending on the Stokes present in the data.  The last in
             each of the 3 rows above == 'FULL'.
             All selected Stokes will be plotted.  They will appear on
             the plot together (and indistinguishably), but will be
             flagged separately following sensible rules adjusted a
             bit by DOALL below.
  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 or
             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 (<= 0) then the task will loop
             over the frequency ID plotting all of them!
  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.
  ANTENNAS...A list of the antennas to plot.  If any number is negative
             then all antennas listed  are NOT desired and all others
             are.   All 0 => list all.
  BASELINE...Baselines are specified using BASELINE.
             Eg. for baselines 1-6,1-8, 2-6 and 2-8
             use ANTENNAS=1,2; BASELINE=6,8.
  UVRANGE....Range of projected spacings to be plotted in 1000's of
             wavelengths.  0  =>  1, 1.E10
  SUBARRAY...Subarray number to plot.        0 => all - the task will
             loop over subarray number.
  BCHAN......Beginning spectral line channel number.   0 => 1.
  ECHAN......Ending spectral line channel number.   0 => max.
  NCHAV......Number of spectral channels to average before plotting.
             0 => 1.  ECHAN will be adjusted downwards so that all
             averages will include the same number of spectral
             channels.
  CHINC......Increment in spectral line channel number.   0 => NCHAV
             Channels i through i+CHINC-1 are flagged if channel i is
             flagged.  All channels may be flagged by setting DOALL.
             CHINC is ignored if NCHAV >= ECHAN-BCHAN+1.
  BIF........First IF number to plot.              0 => 1
  EIF........Last IF number to plot.               0 => highest
  DOCALIB....If true (>0), calibrate the data using information in the
             specified Cal (CL) table for multi-source or SN table for
             single-source data.  Also calibrate the weights unless
             DOCALIB > 99 (use this for old non-physical weights).
  GAINUSE....Version number of the Cal. table to apply to the data if
             DOCALIB=1.  Refers to a CL table for multi-source data or
             an SN table for single-source.  0 => highest.
  DOPOL......If > 0 then correct data for instrumental polarization as
             represented in the AN or PD table.  This correction is
             only useful if PCAL has been run or feed polarization
             parameters have been otherwise obtained.  See HELP DOPOL
             for available correction modes: 1 is normal, 2 and 3 are
             for VLBI.  1-3 use a PD table if available; 6, 7, 8 are
             the same but use the AN (continuum solution) even if a PD
             table is present.
  PDVER......PD table to apply if PCAL was run with SPECTRAL true and
             0 < DOPOL < 6.  <= 0 => highest.
  BLVER......Version number of the baseline based calibration (BL) table
             to apply. <0 => apply no BL table, 0 => highest, if any.
  FLAGVER....Specifies the version of the flagging table to be applied.
             0 => highest numbered table.  <0 => no flagging to be
             applied.  If FLAGVER < 0, no input FG table is used or
             copied.
  OUTFGVER...Flag table version to be used on output for both single-
             and multi-source data sets.  If OUTFGVER is <= 0 or
             greater than FGmax (the previously highest FG version
             number), then a new FG table will be created for the new
             flags with version FGmax+1.  This new table will also
             contain the flags applied on input (if any) from FG
             version FLAGVER.  If OUTFGVER specifies a pre-existing FG
             version, then the input flags are not copied even if
             OUTFGVER and FLAGVER are not equal.
  DOBAND.....(multi-source) If true (>0), then correct the data for the
             shape of the antenna bandpasses using the BP table
             specified by BPVER.  The correction has five modes:
             (a) if DOBAND=1 all entries for an antenna in the table
             are averaged together before correcting the data.
             (b) if DOBAND=2 the entry nearest in time (including
             solution weights) is used to correct the data.
             (c) if DOBAND=3 the table entries are interpolated in
             time (using solution weights) and the data are then
             corrected.
             (d) if DOBAND=4 the entry nearest in time (ignoring
             solution weights) is used to correct the data.
             (e) if DOBAND=5 the table entries are interpolated in
             time (ignoring solution weights) and the data are then
             corrected.
  BPVER......(multi-source) specifies the version of the BP table to be
             applied. 0 => highest numbered table.
  SMOOTH.....Specifies the type of spectral smoothing to be applied to
             a uv database . The default is not to apply any smoothing.
             The elements of SMOOTH are as follows:
             SMOOTH(1) = type of smoothing to apply: 0 => no smoothing
               To smooth before applying bandpass calibration
                 1 => Hanning, 2 => Gaussian, 3 => Boxcar, 4 => Sinc
               To smooth after applying bandpass calibration
                 5 => Hanning, 6 => Gaussian, 7 => Boxcar, 8 => Sinc
             SMOOTH(2) = the "diameter" of the function, i.e. width
               between first nulls of Hanning triangle and sinc
               function, FWHM of Gaussian, width of Boxcar. Defaults
               (if < 0.1) are 4, 2, 2 and 3 channels for SMOOTH(1) =
               1 - 4 and 5 - 8, resp.
             SMOOTH(3) = the diameter over which the convolving
               function has value - in channels.  Defaults: 1,3,1,4
               times SMOOTH(2) used when input SMOOTH(3) < net
               SMOOTH(2).
  BPARM......Control parameters:
     1,2 = type of X-axis and type of Y-axis- where,
       1 = amplitude (Jy),         2 = phase (degrees),
       3 = u,v distance (klambda), 4 = u,v p.a.(deg, N thru E)
       5 = time (IAT days),        6 = u (+max at left, bottom),
       7 = v,                      8 = w (all in klambda),
       9 = real part (Jy)         10 = imaginary part (Jy)
      11 = time (IAT hours)       12 = log (amplitude)
      13 = vis weight             14 = hour angle (hours)
      15 = elevation (degrees)    16 = parallactic angle (deg)
      17 = uv dist. in p.a. ROTATE  18 = azimuth (deg)
      **********************************************
      Use -n to plot the parameter from max at left or bottom to min
      at right or top rather than the usual order (opposite for u).
      **********************************************
     BPARM(1)=0  => 3 -- X-axis type is u,v, distance
     BPARM(2)=0  => 1 -- Y-axis type is Amplitude (Jy)
         For single-dish data: 1 and 9 are flux, 2 and 10 are offset, 3,
         6, and 8 are longitude, 4 and 7 are latitude.
     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.  Each axis treated separately.
     4 = Minimum of X-axis - used if BPARM(5) > BPARM(4).
     5 = Maximum of X-axis - used if BPARM(5) > BPARM(4).
     6 = Minimum of Y-axis - used if BPARM(7) > BPARM(6).
     7 = Maximum of Y-axis - used if BPARM(7) > BPARM(6).
         The value of 0.0 is treated as special, to imply that that
         BPARM (4-7) is to self-scale even when others are fixed scale
         (BPARM(3) > 0).  To get effectively 0, use some small positive
         or negative number.
         Note that phase is initially computed in the range -180 to
         180 degrees, but will be plotted in the range 0 to 360 if
         specified as such.  In self-scaled phase plots, the plot with
         the smaller total range of those two possibilities is used.
         Values > 360 or < -180 are not available.
     9 = radius in pixels of the circular wiper invoked in fat modes.
         0 -> 2 - may be reset interactively
     10  If > 0, then the auto-corelations, if there are any, will also
         be plotted.
     BPARM=6,7,2,0 will generate a UV coverage plot with identical U and
         V limits.
  REFANT.....Hour angle, elevation, and parallactic angle are actually
             antenna parameters not baseline parameters.  If REFANT >
             0, these plot parameters will be those evaluated at
             antenna REFANT.  If REFANT = 0, these parameters are
             evaluated at each antenna of an antenna pair and averaged
             for plotting purposes.
  ROTATE.....Position angle, in degrees N thru E, for the projected uv
             distance.  This parameter is only used if BPARM(1)=17
             or BPARM(2)=17.
  IMSIZE.....The UV plot is made in a memory image IMSIZE(1) by
             IMSIZE(2) pixels.  0 -> size of TV memory.  If this is
             too small, then many samples will be plotted in the same
             pixel and will all be deleted if any are.  If it is too
             large, there will be a heavy demand on computer memory
             and the image will be able to be plotted only in pieces.
             The full sub-image must fit on the TV before you can edit
             but you may select the sub-image interactively.
  DOCENTER...The interactive menu is one column of options.  It is
             hard to read if data fall beneath it.  Rounding to
             nearest integer, if DOCENTER = -1 the menu will appear at
             the upper left, = 1 at the upper center, and = 0 at the
             upper right.  This adverb also controls the positioning
             of the curvalue-like display in a similar manner.
  DOALL......Bit pattern:
             = 1,3,5,7 -> flag all spectral channels in a sample if
                     any one is flagged (e.g. if you plotted only one)
             = 2,3,7   -> flag all IFs if any 1 is flagged.
             = 4,5,6,7 -> flag both parallel polarizations when
                     flagging one (set true on Stokes I plots)
  BADDISK....Disk numbers to avoid for scratch files.  Scratch files may
             be created by the sorting routines if calibration or
             flagging is applied.
----------------------------------------------------------------
WIPER:  Plots and edits data from a u,v data base.
RELATED PROGRAMS: UVPLT, EDITR, TVFLG, SPFLG

                      PURPOSE

     WIPER can be used to display any pair of variables from a u,v
database i.e. any of u, v, w, uv distance, uv position angle,
visibility amplitude, phase, real, imaginary, etc.  It is very useful
as a diagnostic tool to be used to flag obviously bad data.  The
program constructs an IMSIZE image with pixel values being the sum of
the number of UV samples that plot at that pixel position.  Up to two
baseline values are also kept for each pixel.  Note that the actual
data being flagged are not fully identified during flagging although
the value and the 2 baselines are displayed.  Data may be marked "bad"
on a pixel-by-pixel basis including in rectangular areas or in
circular areas.  The latter is a particularly fast way to erase "bad"
data.  When you select EXIT from the menu, the program re-reads the UV
data and creates flags for each UV sample that falls on a flagged
pixel in the original image.

     If IMSIZE is greater than the TV display area, the plot will be
shown on the TV with plot pixels averaged.  In this case, you are only
offered one "option" - to select a sub-image to be displayed at full
resolution.  The smoothed image and the selected images will have plot
labels displayed.

     If IMSIZE or the selected sub-image is smaller than the TV (when
expanded to its maximum size) then you are offered the following
options.  Hit button A, B, or C to get the desired option, hit button
D to get helpful information about the option.
----------------
| OFF ZOOM     |   turn off any zoom magnification
| TVZOOM       |   interactive zoom magnification and center
| SET WINDOW   |   interactive window setting to limit edit/display
                   area
| RESET WINDOW |   turn off any windowing - may force you to select a
                   window before you can edit again
| FLAG POINT   |   flags plot points one at a time on buttons A, B, C
| FLAG AREA    |   flags rectangles of points set in the usual manner
| FLAG FAST    |   flags any point at which the cursor is pointed
| FLAG FAT     |   flags any point within BPARM(9) of where the cursor
                   is pointed
| FLAG BASELIN |   Records flagging for a pair of antennas and marks
                   points appropriately (0 for one => all)
| UNFLAG POINT |   unflags flagged points one at a time with buttons
| UNFLAG AREA  |   unflags flagged points in rectangles
| UNFLAG FAST  |   unflags any flagged point at which cursor is
                   pointed
| UNFLAG FAT   |   unflags any flagged point within BPARM(9) of where
               |   the cursor is pointed
| UNFLAG BASEL |   Removes record of flagging for a pair of antennas
                   and unmarks points appropriately (0 for one => all)
| WIPER SET    |   sets the fat wiper radius graphically with
                   horizontal plot of radius
| WIPER SIZE   |   sets the fat wiper radius graphically with display
                   of wiper in zoom mode
| ABORT        |   exits the task with no flagging saved
| EXIT         |   stops plotting, converts flagging into FG table
----------------
The interactive flagging (unflagging) options are of four types:
(1) The most basic flags unflagged points (unflags flagged points)
    toward which the cursor is first pointed  and then button A, B, or
    C is "pushed".  C causes an exit to the menu after flagging
    (unflagging) the point.
(2) The area type has the user set a rectangular area with the cursor,
    first setting a bottom left corner and then hitting button A to
    set the opposite corner.  Button B or C will cause all unflagged
    (flagged) points in the rectangle to be flagged (unflagged).  C
    causes an exit to the menu after flagging (unflagging) the
    points.
(3) The fast mode requires a button push to get started after which no
    further button pushes are required to flag (unflag) points.  Any
    unflagged (flagged) point selected by the cursor (with left mouse
    button down) will be flagged (unflagged).  After the first button
    hit, hit any button to exit to the menu.
(4) The "fat" mode is a fast mode with a circular cursor of radius
    BPARM(9) pixels.  That radius may be reset by the WIPER SET and
    WIPER SIZE operations.
In all modes, button D exits to the menu with no further flagging.

The FLAG BASELIN and UNFLAG BASEL ask you to enter 2 integers for the
two antennas in the baseline.  A 0 for one will flag all antennas to
the other one - both 0 exits.  They baseline(s) affected are recorded
in a list.  The plotted points are examined and any affected by the
baseline(s) have their attached baseline list modified to record the
flagging or unflagging.  If the plotted point has any "good" baselines
attached after this operation, it will be displayed as good.
Otherwise it will be shown as flagged.  The plot is fully re-drawn
after these operations.

Useful forms of plot axes include:

     1. Plotting visibility amplitude or phase as a function of uv
distance to find a useful uv range for self-calibration.

     2. Plotting visibility amplitude or phase of the residuals of a set
of clean components from a data base as a function of uv distance to
find bad points which can be clipped using task CLIP.  The task UVSUB
can be used to subtract or add the visiblity corresponding to a set of
clean components.  For the purpose of spotting bad visibility points it
is recommended that all clean components up to the first negative be
subtracted before running WIPER.

     3. Plotting u against v will give the uv plane coverage of the data
set.

     4. Plotting visibility amplitude or phase as a function of uv
distance to guesstimate a reasonable value for the zero spacing flux to
be used in IMAGR.  Values > 110-120% of the maximum correlated flux will
lead to spurious results in cleaning.

                     COMMENTS

BCHAN, ECHAN, BIF, EIF:
     More than one frequency may be plotted from multi-channel, multi-IF
data sets.  The data will be plotted at u,v,w values corrected to the
frequency of the individual channel and IF.  This is useful in seeing
the effect of bandwidth synthesis.  IF-dependent and channel-dependent
errors may be spotted and edited in this way.

     Note that multiple subarrays and multiple FREQIDs may be plotted
and flagged.

UVRANGE :
     Allows selection of points to be plotted on the basis of distance
from the centre of the uv plane.

SCALING :
     By choosing the plot scales, you may restrict the editing to a
range of values that you expect to contain bad data.  This will allow
more detailed editing and help the task run faster.
     The default scaling is from the maximum to the minimum of an axis.
The entire data base must be read to determine the scaling so you can
reduce the execution time of WIPER by specifying the maximum and minimum
values.  If BPARM(3) > 0.0, then BPARM(4) - BPARM(7) control the scaling
of the 2 axes. If, however, any of the BPARM4) - BPARM(7) is zero, then
that parameter will be self-scaled.  If you actually want 0.0 for a
limit, set some small negative (for lower limits) or positive (for upper
limits) amount..
     The option of setting BPARM(3) < 0.0 is useful to restrict the data
to some range, but still have a self-scaled plot.  For example, BPARM =
3, 1, -1, 0, 0, 1.0, 10000 will plot amplitudes >= 1.0 against uv
distance, but the amplitude scale will only go up to the peak amplitude
in the data not to 10000 Jy.  The X axis (uv distance) will self-scale
to cover the full range.
