; CLIP
;---------------------------------------------------------------
;! deletes UV data with amplitudes outside specified range
;# Task UV EDITING
;-----------------------------------------------------------------------
;;  Copyright (C) 1995-1996, 1999
;;  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
;-----------------------------------------------------------------------
CLIP      LLLLLLLLLLLLUUUUUUUUUUUU CCCCCCCCCCCCCCCCCCCCCCCCCCCCC
CLIP      Task to flag data whose amplitude is out of range.
INNAME                             Input UV file name (name)
INCLASS                            Input UV file name (class)
INSEQ             0.0     9999.0   Input UV file name (seq. #)
INDISK            0.0        9.0   Input UV file disk unit #
OUTNAME                            Output UV file name (name)
OUTCLASS                           Output UV file name (class)
OUTSEQ           -1.0     9999.0   Output UV file name (seq. #)
OUTDISK           0.0        9.0   Output UV file disk unit #.
BCHAN             0.0     4096.0   Begin channel number.
ECHAN             0.0     4096.0   End channel number.
BIF                                First IF to consider
EIF                                Highest IF to consider
UVRANGE           0.0              UV range in which to apply
                                   clip (kilo wavelengths)
ANTENNAS                           Antennas to consider 0=>all
BASELINE                           Baselines with ANTENNAS
APARM                              Flux range by polarization:
                                   (1) = max. allowed parallel
                                   (2) = max. allowed cross-pol.
                                   (3) = min. allowed parallel
                                   (4) = min. allowed cross-pol.
                                   (5) > 0 => convert to Stokes
                                       before testing amplitudes
                                   (6) > 0 => do not flag cross
                                       because parallel flagged
                                   (7) > 0 => keep all data
                                   (8) > 0 => flag all channels
                                       if >= APARM(8) are
                                       clipped
PRTLEV                             ABS(PRTLEV) clipped UV points
                                   printed
----------------------------------------------------------------
CLIP
Task:  This task will flag all visibilities whose amplitudes are outside
       some range.  If a parallel polarization is flagged, all
       corresponding cross polarized visibilities will also be flagged
       unless APARM(6) > 0.   The number of visibilities flagged is
       reported by the task.  CLIP normally works on the individual
       correlator values, but the test can be performed on the Stokes
       values if APARM(5) > 0.  (NOTE: UVPLT is normally used to plot
       Stokes I making the combination a bit confusing.)
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.
  OUTNAME....Output UV file name (name).     Standard defaults.
  OUTCLASS...Output UV file name (class).    Standard defaults.
  OUTSEQ.....Output UV file name (seq. #). 0 => highest unique.
  OUTDISK....Disk drive # of output UV file. 0 => highest
             with space.
  BCHAN......Begin (line) channel number.    0 => 1.
  ECHAN......End (line) channel number.      0 => highest.
  BIF........Lowest numbered IF to consider.  0 => 1.
  EIF........Highest numbered IF to consider. 0 => highest.
  UVRANGE....Range of projected spacings in kilo wavelengths over which
             the task looks for excess amplitudes.
  ANTENNAS...A list of the antennas to be copied. All 0 => all.
             If any number is negative then all antennas listed are NOT
             to be copied and all others are.
  BASELINE...If any elements of BASELINE are non zero then all baselines
             between antennas named in ANTENNAS and those named in
             BASELINE are specified.  If ANTENNAS contains a negative
             value then all baselines NOT specified are selected.
  APARM......Sets an allowable range in amplitudes (Jy)
                APARM(1) = max. parallel-hand polarization.
                           (IPOL, RR, or LL) 0 => 1.e6
                APARM(2) = max. cross-polarization. 0 -> 1e6.
                           (QPOL, UPOL, VPOL, RL, or LR)
                APARM(3) = min. parallel-hand polarization.
                APARM(4) = min. cross-polarization.
                Note that sign is significant for autocorrelation data
                such as single-dish data.
                APARM(5) > 0 => convert to Stokes before testing
                           the amplitudes.
                APARM(6) > 0 => do not flag cross-polarization
                           correlators when the corresponding
                           parallel-hand ones are flagged.
                APARM(7) > 0 => keep fully flagged data records
                           (else they are omitted from output)
                APARM(8) > 0 => Flagg all spectral channels of an
                           IF/Stokes if >= APARM(8) of them are clipped.
  PRTLEV..... ABS(PRTLEV) clipped UV-data points will be printed.  If
              PRTLEV is < 0, then Real, Imaginary and Weight of UV data
              are also printed.
----------------------------------------------------------------
CLIP:   Task to flag data whose amplitude is out of range.
Related Programs: PRTUV, UVFLG, UVSUB, UVPLT

                           PURPOSE

     CLIP is a task which will flag all visibilities whose amplitudes
are larger than a specified limit or are smaller than a specified limit.
Some interaction between the flagging of correlators is possible.
     The task is the most convenient method for flagging large, spurious
visibility values.  Before serious imaging it is worthwhile to run UVPLT
in order to display the visibility amplitude as a function of UV
projected spacing.  The plot should show a relatively smooth decline of
amplitude versus spacing; the details of which depend of the angular
extent of the source and the signal to noise.  Large amplitude spikes
are generally very obvious and these visibilities can be flagged by
using CLIP over all or some the visibility spacing range.
     NOTE: UVPLT is normally run to display Stokes I - the vector
average of RR and LL.  This vector average can appear ok with bad, high
amplitude RR and LL of different phase or can appear low (and bad) with
ok amplitude RR and LL of different phase.  CLIP will flag the former,
but not the latter in its normal mode.  However, an option allows the
conversion to Stokes in CLIP before testing the amplitudes.  For normal
VLA data, if IPOL or VPOL is bad, RR and LL will be flagged (and RL and
LR depending on APARM(6)) and, if QPOL or UPOL is bad, RL and LR will be
flagged.
     For a bright radio source where the correlated flux density in the
source obscures possible amplitude spikes, the following scheme is
advised.  After getting a reasonably CLEAN image, subtract the clean
components from the visibility data using UVSUB.  The data will now be
more dominated by noise since the majority of flux density from the
source has been removed, and the subsequent use of UVPLT and CLIP can
flag bad data.  Do not forget to add back in the clean components using
UVSUB in the opposite sign in order to get back to the original
visibility data.
     After execution CLIP will report on the number of visibilities
which have been flagged.  The correlator order (1,2,3,4) corresponds to
(RR,LL,RL,LR).  This report is placed into the History file.

                        COMMENTS

OUTNAME, OUTCLASS, OUTSEQ, OUTDISK
     If the name describing the output visibility file is identical to
the name of the input visibility file, the clipped data set will
overwrite the input data set.  This is somewhat dangerous unless the
input data set is backed up, but does save a lot os disk space if
necessary.

UVRANGE
     Set the uv-spacing range (in klambda) appropriately for sources
which are dominated by large and small-scale structure.

APARM
  (1)  Clip any parallel hand vis. amplitude greater than this value.
       0 => no upper limit. (10**6)
  (2)  Clip any crossed-hand vis. amplitude greater than this value.
       0 => no upper limit. (10**6)
  (3)  Clip any parallel hand vis. amplitude less than this value.
       0=>no lower limit.        (-10**6)
  (4)  Clip any crossed-hand vis. amplitude less than this value.
       0=>no lower limit.        (-10**6)
  Sign is significant - autocorrelation data may have either sign while
  cross-correlation data always has positive amplitude.
  (5)  <= 0 => Apply clip limits to the individual correlators found in
       the input data base.
       > 0  => Convert to Stokes visibilities, apply clip limits and
       flag the corresponding correlators.
  (6)  <= 0 => Flag crossed-hand correlators if parallel hand
       correlator(s) are flagged.
       > 0  => Do not flag crossed-hand correlators if parallel hand
       correlator(s) are flagged.
  (7)  <= 0 => Do not pass full flagged records to the output file.
       > 0  => Pass all records to the output, even if fully flagged.
  (8)  > 0  => Flag all spectral channels of a given IF and Stokes if
       APARM(8) or more of them exceed the clip limit.
       <= 0 => Flag spectral channels individually.

PRTLEV
     Gives the number of UV data points clipped to be printed.  If
pRTLEV is positive only the Visibility number, U, V, two baseline
antennas and the time (in days) are printed; i.e., if PRTLEV = 1 then
the following is printed

       CLIP      VIS NUM  U(LAMBDA) V(LAMBDA)  A1 A2 TIME(DAYS)
       CLIP            12  1.18E+05  2.84E+05   6 10 3.14931E-01

If PRTLEV =-1 then the real, imaginary and weights are printed for all
STOKEs and IFs, but only for the first spectral CHANNEL (BCHAN). Below
is a 4 Stokes, 2 IF output:

       CLIP      VIS NUM  U(LAMBDA) V(LAMBDA)  A1 A2 TIME(DAYS)
       CLIP            12  1.18E+05  2.84E+05   6 10 3.14931E-01
       CLIP      IF STOKE   REAL    IMAGINARY  WEIGHT
       CLIP        1    1  9.44E-01 -4.53E-02 -1.0E+00
       CLIP        1    2  9.28E-01 -8.85E-03 -1.0E+00
       CLIP        1    3  3.64E-03  6.85E-02 -1.0E+00
       CLIP        1    4  1.65E-02 -5.34E-02 -1.0E+00
       CLIP        2    1  0.00E+00  0.00E+00  0.0E+00
       CLIP        2    2  9.93E-01 -2.59E-02  1.0E+00
       CLIP        2    3  0.00E+00  0.00E+00  0.0E+00
       CLIP        2    4  0.00E+00  0.00E+00  0.0E+00
;---------------------------------------------------------------



