; UVLIN
;---------------------------------------------------------------
;! Fits and removes continuum visibility spectrum, also can flag
;# TASK UV EDITING SPECTRAL
;-----------------------------------------------------------------------
;;  Copyright (C) 1995, 1999-2001
;;  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
;-----------------------------------------------------------------------
UVLIN     LLLLLLLLLLLLUUUUUUUUUUUU CCCCCCCCCCCCCCCCCCCCCCCCCCCCC
UVLIN     Fits and removes continuum visibility, also can flag
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 #
INFILE
                                   File with channel weights
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 #.
SHIFT                              Shift in asec to RA, DEC
FLUX              0.0              Threshold for unity weight
DOCONT                             Retain continuum if > 0
ICHANSEL                           Select channels to fit: NOTE
                                   this is start,end,increment
                                   and IF for each region
ORDER             0.0        1.0   Order of fit line (0 -> DC)
PRTLEV           -1.0        2.0   Print level: 0 very little
                                   1 flag summary, 2 channels
                                   used and flagged
----------------------------------------------------------------
UVLIN
Task:  This task does a continuum emission subtraction by making
       linear fits to the real and imaginary components versus channel
       number for each visibility and subtracting the appropriate
       values from all channels.  Uses the residual values on the
       designated channels to decide on flagging.  The user specifies
       the threshold appropriate for a 10 sec integration and the test
       is done taking into account the weight of the data point.  Be
       conservative (6 - 8 times the theoretical sigma is a good
       default choice). IMLIN is the image plane analog of UVLIN.
       UVBAS is similar but inferior to UVLIN.  UVLSF is similar to
       UVLIN, but offers different flagging options and is able to
       write an aoutput "continuum" data set based on the fit.
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.
  INFILE.....File with channel weights. Specify path in usual way e.g.
             LOGICAL:FILE.  If this is blank then ICHANSEL is used.
             The format of the file is one row per channel containing
             channel number, IF number, and a weight which has to be 1
             to use the channel for fitting and interference testing
             or 0 if the channel should be ignored (these unwanted
             channels can be omitted).  Use at least one blank
             character at the beginning of the line and one in between
             the channel number, the IF number, and the weight (for an
             example, see below).  An IF number of 0 is taken to apply
             to all IFs.
  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 for the file.
  SHIFT......Shift in arcseconds during fitting process. The data
             are shifted, fitted, flagged and then shifted back.
             These are shifts in RA, DEC (i.e. NOT on the tangent
             plane) and are the same as in UVFIX.
  FLUX.......Max. residual flux allowed for unity weight.  If the
             data weights represent 1/rms**2 as expected, then FLUX
             should be 6-8 since a weight 1 channel has an rms of 1
             Jy.  The test is actually, if
                    ABS(residual) > FLUX * SQRT (weight)
             then all channels are flagged for that correlator.  The
             threshold is applied to the residuals after subtracting
             the best linear fit.
  DOCONT.....Retain continuum if > 0. If so, the routine will
             simply flag bad data.  If <,= 0, it will write the
             residual values after subtracting the best line fit
             to the real and imaginary components of each vis.,
             flagging as well as flagging noisy data as above.
  ICHANSEL...Select up to 20 groups of channels/IF(s) to fit as sets
             of (Start,end,inc,IF), i.e., ICHANSEL = 6,37,1,0,
             92,123,1,0 for two regions applyingto all IFs.  The first
             group for which ICHANSEL(2,i) <= 0 ends the list.
             Defaults: Any IF having no group assigned to it, gets a
             group including all channels.
             ICHANSEL(1,j) defaults to 1,
             0 < ICHANSEL(2,j) < ICHANSEL(1,j) defaults to Nchan.
             ICHANSEL(3,j) < 1 or > ICHANSEL(2,j)-ICHANSEL(1,j)+1
             defaults to 1.
             ICHANSEL(4) <= 0 => this group applies to all IFs.
  ORDER......Normally the fit should be done with a first order
             polynomial, namely a DC term and a slope.  If only one box
             is used, the slope may not be adequately defined and a
             simple DC term for the real and for the imaginary parts
             would be more reliable.
  PRTLEV.....Print level. > 0 => print summary of data flagged.
             > 1.5 => print mask of channels used for baseline and
             print summary by channel of data flagged.
----------------------------------------------------------------
UVLIN: Task which subtracts continuum from channels in UV-plane

			PURPOSE

UVLIN fits and removes the continuum emission in the UV-plane.
The fit is performed using the specified weights (allowing one
to ignore frequencies for which lines are present). UVLIN fits
in real and imaginary parts of the visibility and is therefore
much superior to UVBAS which fits in amplitude and phase.

			PARAMETERS

SHIFT: since UVLIN works perfectly for a single point source at
the phase center, one should shift any dominant point source to
the phase center prior to the fitting process. Note that UVFIX
does this incorrectly since it ignores the relative phase shift
between channels. THIS SHIFT IS UNDONE AFTER THE FIT. The
sense of the shift is the same as in UVFIX. The code for
computing the shift is:

         RA = RA + SHIFT(1) / 3600.
         DEC = DEC + SHIFT(2) / 3600.
         DTORAD = 3.14159265358979326D0 / 180.0D0
         DXC = SIN (DTORAD * (SHIFT(1)/3600.)) *
     *      COS (DEC * DTORAD)
         DYC = COS ((DEC - SHIFT(2)/3600.) * DTORAD) *
     *      SIN (DEC * DTORAD) - SIN ((DEC  - SHIFT(2)/3600.) *
     *      DTORAD) * COS (DEC * DTORAD) * COS ((SHIFT(1)/3600.) *
     *      DTORAD)
         DZC = SQRT(1.0D0-DBLE(DXC)**2-DBLE(DYC)**2)-1.0D0

For small shifts, the necessary values for SHIFT can be
measured from an image and adjusted by dividing the RA value by
cos(declination).

FLAGGING of the data on the basis of discrepancy in the fit can be
performed using FLUX: the maximum error allowed per channel for
for a weight of 1 (Jy). This is very useful for removing narrow-band
interference. The number specified is the limit per weight.  This is
adjusted by 1/sqrt[visibility weight] to correct for integration time,
bandwidth, and receiver differences.  Note that although flags are
only triggered by the channels for which the fitting is done (i.e.,
those designated by the user with INFILE or the array BOX), the
flagging is performed on all channels for a given correlator. This is
done to avoid changes in the synthesized beam as a function of
frequency that could result in spurious spectral features.  Flagging
will be minimized by setting FLUX to a suitably large number (the
default, 0, corresponds to 1.0E20). We recommend using TVFLG on any
channel of the output of UVLIN to find out what flagging has been
done. For example, if 80% of a baseline is flagged, the user might
want to delete such baseline entirely unless there is a clear reason
why UVLIN has done such flagging (if all flags are contiguous maybe
the baseline had some problem that was fixed like interference from a
transmitter that only operated during some specific time interval).

CONTINUUM subtraction is enabled by setting DOCONT less than or equal
to zero.  Otherwise the program passes the continuum and only flags
the bad points.

WEIGHTs can be specified by either using NBOXES and BOX or by an input
file. The fit is performed using only those channels with non-zero
weights but the subtraction is done for all channels.

Example of weights file:

   1   0     0
   2   1     1
   3   0  1
   4   0   1
 5  0     1
 6     0     1
 7   1      0
 8    1      0
   9   0    1
  10  0    1
  11   0      1
  12   0  1
  14   1  1
  15   0    0
  7   2    1
  8   2    1

where channel 13 is missing, so its weight will be zero.  The format
is free but do not use tabs nor other control characters except for
new-line (return). The last line must end with a new-line (return).
To accomplish the same thing with ICHANSEL:

ICHANSEL = 3,6,1,0, 9,12,1,0, 2,2,1,1, 14,14,1,1, 7,8,1,2
If INFILE is blank and ICHANSEL is 0 for an IF, then all channels are
used for that IF.

PRTLEV is used to write flagging statistics to message file if >0.
The total number of visibilities present per correlator is printed
as well as the percentage flagged.  In addition, the program reports
how often each channel has triggered the flagging (PRTLEV>1.5).  If
one or a few channels are responsible for most of the flags, the user
might decide to give up on those channels and exclude them from the
test.  Images of the remaining channels should then have lower noise
as more visibilities will be used in making them.  This option used to
be restricted to the VLA; it no longer has such a short-sighted limit.


			REFERENCES

See Cornwell, Uson and Haddad (Astron. Astrophys. 258, 583; 1992) for a
detailed discussion which includes estimates of errors. Here is a brief
excerpt which summarizes the key attributes of UVLIN and a complementary
task, IMLIN.

	- If the continuum emission is spread over a sufficiently small
field of view, either the IMLIN or the UVLIN image will represent the
line emission well. Both may be deconvolved to produce high dynamic
range in the line. The noise level of IMLIN images varies within
position, whereas that of the UVLIN image is approximately constant.
In the presence of a point source of continuum strength S, the errors
for a small field of view are

IMLIN:

                         (theta)^2
         S (sigma_B)^2  -----------
                        (theta_F)^2

UVLIN:

                        (theta_0)^2
         S (sigma_B)^2  -----------
                        (theta_F)^2


where theta is the distance from the point source, theta_0 is the
distance of the point source to the phase center, the angular distance
theta_F is the ratio of the observing-frequency to the bandwidth times
the full-width at half maximum of the synthesized beam and sigma_B is
the sidelobe level of the synthesized beam.

	- For these methods to work well, the continuum emission must
therefore lie within a field of view theta_F, centered on the strongest
source for IMLIN, and centered on the phase tracking center for UVLIN.
This field of view may be extended by using UVSUB to pre-subtract the
brightest sources.
	- For larger fields of view, both IMLIN and UVLIN might fail
completely.
	- When imaging small fields in the presence of instrumental
errors or time-variable sources, both IMLIN and UVLIN are quite robust.
	- Both IMLIN and UVLIN have a considerable speed advantage over
UVSUB, especially for low frequency observations because of the extent
of sidelobe confusion.

There seems little in this list of attributes of IMLIN and UVLIN to
favor conclusively one method over the other. The clearest advantage
occurs in the case of weak line emission in the same field as a very
much brighter point continuum source, where UVLIN with a phase shift of
the point source to the phase center will be almost error free. In the
case of continuum power spread fairly uniformly over the field, neither
will win out decisively.  The difference in failure modes makes the
methods complementary and so both should probably be used, each as a
check on the other. In any event, the error levels can be estimated
using our formulae.

A key advantage of UVLIN occurs in the presence of interference (RFI).
UVLIN's check for consistency of the channel residuals to the linear
fit has proven to be a very effective filter of corrupted data.  We
recommend using UVLIN in both its modes of retaining the continuum as
well as discarding it (i.e. DOCONT = 1,-1).  The first output can then
be used to make an image cube and subsequently use IMLIN to obtain
both continuum and spectral images.  This, of course, images and
Cleans the continuum (differently) for each spectral channel.  The
continuum image should be made from a continuum data set, such as the
one written by UVLSF.  Imaging of the second output results directly
in the spectral image cube - the better route.
