; IMLIN
;---------------------------------------------------------------
;! Fits and removes continuum emission from cube
;# TASK ANALYSIS SPECTRAL
;-----------------------------------------------------------------------
;;  Copyright (C) 1995, 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
;-----------------------------------------------------------------------
;---------------------------------------------------------------
IMLIN     LLLLLLLLLLLLUUUUUUUUUUUU CCCCCCCCCCCCCCCCCCCCCCCCCCCCC
IMLIN     Fits and removes continuum emission from cube
INNAME                             Input image name (name)
INCLASS                            Input image name (class)
INSEQ             0.0     9999.0   Input image name (seq. #)
INDISK            0.0        9.0   Input image disk unit #
INFILE
                                   File with channel weights
OUTNAME                            Output image name (name)
OUTCLASS                           Output image name (class)
OUTSEQ           -1.0     9999.0   Output image name (seq. #)
OUTDISK           0.0        9.0   Output image disk unit #.
BLC                                Bottom left corner of input
TRC                                Top right corner of input
YINC              0.0      128.0   Do every YINCth row
ZINC              0.0      128.0   Do every ZINCth plane
DOOUTPUT         -1.0        1.0   Write images of parms
ORDER            0.0          4.0  Max order of polynomial: 1.0
                                   is recommended (see EXPLAIN)
NBOXES           0.0         40.0  Number of spectral regions to
                                   be used in fitting
BOX              0.0       4096.0  Pairs of begin and end
                                   channels for spectral regions
BADDISK                            Disk(s) to avoid for scratch
----------------------------------------------------------------
IMLIN
Task:  Fits and removes continuum emission from spectral cubes.
       This is a very good way of removing continuum emission
       from spectral-line data. The input cube must be
       transposed to 312 order. The UV-plane analog of IMLIN
       is UVLIN. The principal advantage of IMLIN over UVLIN
       is that the window can be varied spatially.  This can
       only be done, however, by using windows and then
       reconstructing the data cube later with MCUBE.  For more
       detailed control of the baseline regions, the interactive
       task XBASL should be tried.
Adverbs:
  INNAME.....Input image name (name).       Standard defaults.
  INCLASS....Input image name (class).      Standard defaults.
  INSEQ......Input image name (seq. #).     0 => highest.
  INDISK.....Disk drive # of input image.   0 => any.
  INFILE.....File with channel weights. Specify path in usual way
             e.g. LOGICAL:FILE.  The format of the file is one row
             per channel containing channel number and a weight
             which has to be 1 if the channel is to be used for
             fitting. Use at least one blank at the
             beginning of the line and one in between the channel
             number and the weight (for an example, see below).
             If this is blank then NBOXES and BOX are used
  OUTNAME....Output image name (name).      Standard defaults.
  OUTCLASS...Output image name (class).     Standard defaults.
             Used only for the corrected image.
  OUTSEQ.....Output image name (seq. #).   0 => highest unique.
  OUTDISK....Disk drive # of output image. 0 => highest
             number with sufficient space.
  BLC........Bottom right corner in input image of desired
             subimage.  Default is entire image.
  TRC........Top right corner in input image of desired
             subimage.  Default is entire image.
  YINC.......Do only every YINC'th row (beginning at BLC(2)).
  ZINC.......Do only every ZINC'th plane (beginning at BLC(3)).
  DOOUTPUT...True (> 0) requests that the constant, slope and
             uncertainty images be catalogued (see OUTCLASS).
  ORDER......The maximum allowed order for the polynomial.  0
             is a constant, 1 is linear, 4 is a bit much and is
             the maximum allowed. 1 should be fine in most cases
  NBOXES.....The number of regions in the spectrum to be
             used in fitting the baseline.
  BOX........NBOXES pairs of channel numbers specifying the
             beginning and end channel numbers of each of the
             regions to be used in the fitting (see EXPLAIN
             file for an example)
  BADDISK....Disk drives to avoid for scratch files.
----------------------------------------------------------------
IMLIN: Task which removes continuum emission from images
DOCUMENTOR: T.J. Cornwell (NRAO/VLA)

			PURPOSE

IMLIN is designed to remove the continuum emission from spectral
line dirty cubes.  The continuum emission is estimated from a
linear (or non-linear if you wish) fit to selected channels and
then subtracted.  It is complementary to UVLIN and provides
roughly the same capability but without the flagging allowed by
UVLIN.

ORDER OF FIT:   We recommend ORDER=1 since this should be adequate and
does not risk erroneously removing part of the line emission. This case
has been extensively analysed (see references) and its error performance
is well-understood.

DIAGNOSTICS: DOOUTPUT=1 will write out 2D images containing the
parameters of the fit (CONT and SLOPE) and the errors (DCONT and
DSLOPE). This is very useful for diagnostic purposes.

WINDOW: The window within which the fit is performed is
specified by NBOXES and BOX. Note that unlike UVLIN, IMLIN can
be used in cases where the line shifts in frequency with
spatial position. Use BLC and TRC to select parts of the input
image.

WEIGHTs can be specified by either using NBOXES and BOX or
by an input file. A non-zero weight is taken to be unity.

Example of weights file:

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

where channel 13 is missing, so its weight will be zero.  To
accomplish the same thing with NBOXES:

NBOXES=3
BOX=2, 6, 9, 12, 14, 14

If INFILE is blank and NBOXES=0 then unity weights are used.

			REFERENCES

This program is best described in the preprint by Cornwell,
Uson and Haddad (1991) entitled "Radio Interferometric imaging
of spectral lines: the problem of continuum subtraction",
submitted September 1991 to Astron. & Astrophys. Here is an
excerpt which summarizes the performance of IMLIN and UVLIN.


	- 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:

sigma^2_B (theta)^2
          -------
          (theta_F)^2

UVLIN:

sigma^2_B (theta_0)^2
          -------
          (theta_F)^2

where theta is the distance from the point source, theta_0 is
the distance of the point source from the phase center and
theta_F = freq/bandwidth synthesized beams. 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 will
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.
