; USUBA
;---------------------------------------------------------------
;! Assign subarrays within a uv-data file
;# TASK UV CALIBRATION
;-----------------------------------------------------------------------
;;  Copyright (C) 1995, 1996
;;  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
;-----------------------------------------------------------------------
;---------------------------------------------------------------
USUBA     LLLLLLLLLLLLUUUUUUUUUUUU CCCCCCCCCCCCCCCCCCCCCCCCCCCCC
USUBA     Task to assign subarrays within a uv-data file
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 #
OPCODE                             Opcode:
                                    Automated identification:
                                    'SCAN': print only.
                                    'AUTO': modify data.
                                    else, use INFILE or input
                                    adverbs to define subarrays

                                   Subarray selection:
TIMERANG                           Time range to use. 0=>all
ANTENNAS          0.0       50.0   Antenna numbers 0=>all
SOURCES                            Source list
FREQID                             Frequency id.
SUBARRAY          0.0     1000.0   Subarray, 0=>next
INFILE                             External text file; subarray
                                   selection adverbs ignored in
                                   this case.
----------------------------------------------------------------
USUBA
Task:  This task allows the user to assign multiple subarrays
       within a uv-data file. Both the uv-data records and
       the associated tables are updated to reflect the new
       subarray assignments. A single subarray can be assigned
       using the input adverbs. Alternatively, multiple subarray
       selections can be specified in an external text file. A
       third option will automatically assign subarray numbers
       after finding all instances of subarraying in the
       uv-data file. This task does not modify times or antenna
       numbers. Certain homogeneity tests are applied to
       existing subarrays before the task will run.
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.
  OPCODE.....Subarray assignment method:
             Automated subarray identification and assignment:
             'SCAN' : print only; no subarrays updated.
             'AUTO' : subarray labelling updated in the data.
             else, use the input adverbs or the external text
             file to define the subarray selection. Note: the
             subarray selection adverbs are used only if
             INFILE is not set and neither OPCODE='SCAN' nor
             OPCODE='AUTO' is used.
  TIMERANG...Time range of the specified subarray. In order:
             Start day, hour, min. sec,
             end day, hour, min. sec. Days relative to ref.
             date.
  ANTENNAS...The antenna numbers to be moved to the new
             subarray. All zeroes => all antennas.
  SOURCES....Source list.  If the data is a multi-source file
             USUBA will move the specified source(s) to the
             new subarray subject to the constraints of antenna
             number and time range. If SOURCE = ' ' then only
             the time range and antenna list are used.
             If the data is a single source file no source name
             need be specified.
  FREQID.....The frequency id. of the data to be moved to the
             new subarray. Less than zero => ignore freq. id.
  SUBARRAY...The specified data will be moved to this subarray.
             0 => the next higher subarray; ex., if 5 currently
             exist, a sixth will be created.
  INFILE.....Name of an external text file containing a list
             of subarray selection records. Type EXPLAIN USUBA
             for details concerning the required format. If
             INFILE is specified then the input adverbs defining
             subarray selection are not used.
----------------------------------------------------------------
USUBA: Task to assign subarrays within a uv-data file
Documentor: A. J. Kemball
Related programs: FITLD, INDXR, LISTR

                       PURPOSE

USUBA can be used to assign multiple subarrays within a uv-data
file. The subarrays are defined through either the input adverbs, an
external text file or by utilising an option to re-number all
subarrays automatically. USUBA can be used for any interferometer
dataset but may be specifically required for VLBA data correlated with
subarrays. Subarrays are not necessarily identified correctly by FITLD
at present for such datasets.

                        OVERVIEW

USUBA can operate in three distinct modes:

OPCODE = 'AUTO'
 In this case the subarrays are identified and labelled automatically.
An algorithm is used which minimizes the overall number of subarrays
and maximizes continuity in subarray properties. For OPCODE='SCAN',
the results of automatic subarray identification are printed but the
data are not changed.

OPCODE = ' ' and INFILE = external file
 If an external text file is specified it is expected to contain a
sequence of subarray selection records in the format given below. This
option is useful, and recommended, if the subarray properties of the
dataset are simple and well-known.

OPCODE = ' ' and INFILE = ' '
 In this case one subarray assignment is performed, as defined by the
subarray selection input adverbs. The resulting subarray number is
specified by adverb SUBARRAY.

               FORMAT OF EXTERNAL TEXT FILE

The external text file, referenced through adverb INFILE, recognizes
the following KEYIN keywords:

 ANTENNAS => array of antenna numbers
 SOURCES  => array of source names
 TIMERANG => start day, hour, min, sec, end day, hour, min, sec.
             (relative to reference date in uv-data file)
 FREQID   => frequency id.
 SUBARRAY => desired subarray number; (default: next highest
             subarray).

The file is expected to contain one or more KEYIN records, separated
by the KEYIN marker '/', each of which define a subarray selection
condition. All of the keywords are optional within any given record.
If a specific keyword is absent, that condition is not applied in
determining a subarray match. The selection conditions are not
checked for internal consistency; the last correct match is used
in defining the new subarray identifications.

Example:

! Subarray selection condition 1
  ANTENNAS = 1, 3, 4, 5
  SOURCES = '3C273', '1611+343'
  FREQID = 1
  SUBARRAY = 3 /

! Subarray selection condition 2
  ANTENNAS = 6, 7, 8, 9
  SUBARRAY = 4 /

-------------------------------------------------------------------------







