; 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.