; UVCOP
;---------------------------------------------------------------
;! Task to copy a subset of a UV data file
;# Task UV
;-----------------------------------------------------------------------
;;  Copyright (C) 1995, 1997-1998
;;  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
;-----------------------------------------------------------------------
UVCOP     LLLLLLLLLLLLUUUUUUUUUUUU CCCCCCCCCCCCCCCCCCCCCCCCCCCCC
UVCOP     Task to copy selected times and channels of uv data.
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 #.
SELBAND                            Bandwidth to select (kHz)
SELFREQ                            Frequency to select (MHz)
FREQID                             Freq. ID to select. 0=> all
BCHAN             0.0     9999.    First channel selected.
ECHAN             0.0     9999.    Last channel selected.
BIF               0.0      100.0   Lowest IF number 0=>all
EIF               0.0      100.0   Highest IF number 0=>all
SOURCES                            Source list
QUAL            -10.0              Source qualifier -1=>all
UVRANGE                            Annulus in uv plane selected
                                    (thousands of wavelengths)
TIMERANG                           Timerange:
                                    1-4 = start day,hr,min,sec
                                    5-8 = end   day,hr,min,sec
ANTENNAS                           Antennas to copy 0=>all
BASELINE                           Baselines with ANTENNAS
SUBARRAY           0.0             Limit copy to one subarray
                                   0 => all.
FLAGVER           -1.0             FG table to apply to data
                                   <= 0 => do not apply
UVCOPPRM                           Flags:
                                    1 > 0 => keep flagged data
                                    2 > 0 => drop subarray info
                                    3 = 0 => copy xc and ac data
                                      = 1 => copy only xc data
                                      = 2 => copy only ac data
                                         of antennas, named in
                                         antenna list. Baseline
                                         list must be zero.
                                    4 > 0 => report progress
                                    5 => clip data with weights
                                         below this limit
NCOUNT                             If UVCOPPRM(3) = 2 then
                                   NCOUNT is the approximate
                                   ratio of AC to XC in file.
----------------------------------------------------------------
UVCOP
Task:  This task will copy a subset of a uv data base selected by time
       range, IF, frequency channel and subarray.  It can apply a flag
       table to the data and is able to apply up to 50000 flags to a
       time (10 times the usual limit).  It also removes any random
       parameters called REMOVED which use up disk space for no good
       reason.  By default, UVCOP will delete all fully flagged samples,
       and it can be used to delete data with weights below a limiting
       value.  It may also be used to wipe out all distinctions between
       data from different subarrays.
       When selecting a FREQID > 1 the FREQID in the output file will be
       changed to 1.  The task will loop over FREQID if none is
       specified.  When selecting a single subarray or removing the
       distinction between subarrays, the output subarray will be
       numbered 1.
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 w room
  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.
  SELFREQ....Frequency of data to be selected. 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. (.le. 0 => all). If you select
             data with the FREQ adverbs UVCOP will renumber the
             FREQID in the output file to 1, i.e. you can set
             FREQID to the default value for all subsequent
             operations on the output file.
  BCHAN......First frequency channel selected. 0 => all or cont.
  ECHAN......Last channel selected. 0 => all (or continuum).
  BIF........First IF to copy. 0=>all.
  EIF........Highest IF to copy. 0=>all higher than BIF
  SOURCES....List of sources to copy.  '*' or ' ' = all; a "-"
             before a source name means all except ANY source
             named.
  QUAL.......Only sources with a source qualifier number in the
             SU table matching QUAL will be used if QUAL is not
             -1.
  UVRANGE....Range (min, max) of projected baselines to include;
             values are in 1000's of wavelengths at the
             reference frequency in the input data.
             0,0 => all baselines.
  TIMERANG...Timerange specified: 1-4 = start day,hr,min,sec
                                  5-8 = end day,hr,min,sec
                start time = 0 => do from beginning; end time
                =0 or <= start time => do to end of data
  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...Baselines between antennas named in ANTENNAS and those
             named in BASELINE are selected..  There are four possible
             combinations of ANTENNAS and BASELINE:
             1. ANTENNAS = 0; BASELINE = 0.
                All possible baselines are selected.
             2. ANTENNAS <>0; BASELINE = 0.
                a)All ANTENNAS > 0
                  Baselines including an antenna in the ANTENNAS list
                  are selected;
                b)Some ANTENNAS < 0
                  All baselines NOT including an antenna in the ANTENNAS
                  list are selected;
             3. ANTENNAS = 0; BASELINE <> 0.
                a)All BASELINE > 0
                  Baselines including an antenna in the BASELINE list
                  are selected;
                b)Some BASELINE < 0
                  All baselines NOT including an antenna in the BASELINE
                  list are selected;
             4. ANTENNAS <> 0; BASELINE <> 0.
                a)All ANTENNAS>0 and all BASELINE>0
                  Baselines between antennas named in ANTENNAS and those
                  named in BASELINE are selected.
                b)Some ANTENNAS<0 .OR. some BASELINE<0
                  Baselines between antennas named in ANTENNAS  and
                  those named in BASELINE are DE-selected, all others
                  are selected.
  SUBARRAY...> 0 => copy only specified subarray, renumbering it as
             number 1.  <= 0 => copy all subarrays and do no
             renumbering.
  FLAGVER....IF > 0, apply flag table version FLAGVER to the data
             (permanently) flagging the data.  Fully flagged records may
             be dropped but only if UVCOPPRM(1) <= 0.
             Note: FLAGVER = 0 means no flagging here.
  UVCOPPRM...UVCOPPRM(1) > 0 tells the program to copy fully flagged
                data, otherwise they are dropped.
             UVCOPPRM(2) > 0 tells the program to drop all distinctions
                between subarrays (not advised).
             UVCOPPRM(3) tells the program which type of data to copy;
                0 => copy all data types; 1 => copy only cross-power
                data; 2 => copy only total-power data.
             UVCOPPRM(4) > 0 keeps you informed about UVCOP progress,
                listing every 10,000th visibility and associated time
                stamp.
             UVCOPPRM(5) => used to set a lower limit for allowed
                weights. All data with weights lower than this will not
                be copied if UVCOPPRM(1)<=0.
  NCOUNT.....Is the ratio of AC data to XC data. Is used when
             UVCOPPRM(3) = 2 to create an output file that is
             approximately the correct size, rather than one
             which is far too big.
---------------------------------------------------------------
UVCOP: Task to copy a subset of a uv data base.
RELATED PROGRAMS:  UVLOD, UVFLG, UVSRT, INDXR

                   PURPOSE

UVCOP copys a subset of a uv data set.  The subset is specified
by a timerange and frequency channel.  The program also can be
used to make an unmodified copy of a uv data base.  Additional
options determine whether or not fully flagged data are copied
and subarray information retained.

                   COMMENTS

BCHAN, ECHAN:
     These adverbs allow selecting frequency channels in a uv
database.  The channel numbers are one-relative to the first
channel contained in the data base; zeros for these values
indicate that all data are to be copied.

     Note: if UVCOP is being used to strip the "channel 0" =
continuum channel from a VLA spectral line data base, the
resulting database will have an incorrect frequency in the
header.  This should be corrected by PUTHEAD or other means
BEFORE the data are used.

ANTENNAS, BASELINE
  Antennas to be copied are specified in array ANTENNAS and/or BASELINE.
If any antenna number is negative the absolute value will be used and
all antennas listed will be deselected, i.e. the described operation
will be done on all OTHER antennas.  If both ANTENNAS and BASELINE have
non zero values, then a set of baselines are specified between the
antennas listed in the one and those listed in the other.  It either
array contains a negative, then all specified antennas or baselines are
omitted, otherwise the specified ones are copied.

If UVCOPPRM(3) = 2, then auto correlations of antennas, named in ANTENNA
or in BASELINE, are copied.  In this case, it is best if one of ANTENNA
and BASELINE is set to zero; otherwise unexpected results can occur (see
the last example below).

Examples:
     If ANTENNAS = 1,2,3 and BASELINE = 4,5 then baselines
1-4, 2-4, 3-4, 1-5, 2-5 and 3-5 are selected.

     If ANTENNAS = -1,2,3 and BASELINE = 4,5 then ALL baselines
EXCEPT 1-4, 2-4, 3-4, 1-5, 2-5 and 3-5 are selected.

     If ANTENNAS = 1,2 and BASELINE = 0 and UVCORPRM(3) =2 then
1-1 and 2-2 will be copyed.

But
     If ANTENNAS = 3,4 and BASELINE = 1,2 and UVCORPRM(3) = 2 then
1-1 and 2-2 will be copyed and not 3-3 and 4-4.

UVCOPPRM:
    UVCOPPRM(1) is a logical flag (> 0.0 => true) telling the
task to copy fully flagged visibility records.  If the data
are heavily flagged, the default can produce a significantly
smaller data file. UVCOPPRM(5) can be used to flag all data
with weights below a limiting value.
    UVCOPPRM(2) is a logical flag (> 0.0 => true) telling the
program to remove all distinctions between subarrays.  The
subarray number is dropped, the times are corrected by 5 days
(times the subarray number - 1), and only antennas file # 1 is
copied.  Note: this can confuse two non-identical antennas each
numbered "n".  It can also cause a loss of the true date and
frequency of observation.  Do not run UVFIX on a file produced
with this option (without considerable thought).


EXECUTION TIMES:
     The run time in an otherwise empty VAX is about 12 seconds
for each 10,000 uv data points.
