; IMAGRPRM
;---------------------------------------------------------------
;! Specifes enhancement parameters for OOOP-based imaging
;# ADVERB IMAGING
;-----------------------------------------------------------------------
;;  Copyright (C) 2002-2003
;;  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
;-----------------------------------------------------------------------
IMAGRPRM  LLLLLLLLLLLLUUUUUUUUUUUU CCCCCCCCCCCCCCCCCCCCCCCCCCCCC
----------------------------------------------------------------
IMAGRPRM
Type: Adverb  (array(20))
Use:  To specify correction and other "enhancement" parameters to
      IMAGR .  See EXPLAIN IMAGR for further discussion.

IMAGRPRM(1) If > 0 then make frequency dependent primary beam
     corrections assuming an antenna diameter of IMAGRPRM(1) meters.
     Can change with TELL which only makes sense if you are going to
     repeat the subtraction with a filtered set of components (see
     IMAGRPRM(8)).

        (2) Visibility amplitudes will be corrected to the average
     frequency assuming a spectral index of IMAGRPRM(2).  Note: the
     typical optically thin synchrotron spectral index is about -0.7.

        (3) If > 0, then the u,v and w terms are scaled by IMAGRPRM(3)
     before imaging.

        (4) If > 0, then SDI Clean will be used when the ratio of the
     maximum residual and the level to load into the AP is < (1 +
     GAIN*IMAGRPRM(4)).  <= 0 -> never use or allow SDI Clean.  Can
     change with TELL.  If SDI Clean is enabled, the output CC files
     will have been merged.

        (5) If > 0 then scaling of residuals is requested and

        (6) Half-width in x of box to determine the dirty beam area
     (default = 5)

        (7) Half-width in y of box to determine the dirty beam area
     (default = 5)  Can change (5)-(7) with TELL.

        (8) If non-zero, select only those Clean components having >
     ABS(IMAGRPRM(8)) Jy within a radius of IMAGRPRM(9) cells of the
     component.  If IMAGRPRM(8) < 0, the abs value of the flux near
     the component is used.  This is an optional filter to remove weak
     isolated components which can cause a significant bias.  Can
     change with TELL but only if it was non-zero to begin with.  A
     copy of the input data has to be made for this option and it is
     only made if IMAGRPRM(8) is non-zero.  If this option is
     selected, the output CC files will have been merged.  Note that
     IMAGRPRM(8) should always be <= 0 for images of Q, U, and V
     Stokes parameters since negative brightnesses are valid.
     Filtering is done on restarts, when requested from the TV, on
     certain Cleaning failures, and on exit.  If ALLOKAY >= 2, the
     filter is not applied on the restart.  If the filtering option
     was selected at the start (IMAGRPRM(8) non zero), it may be
     turned off by setting IMAGRPRM(8) exactly 0 and running TELL.  To
     delete all negative regions, set IMAGRPRM(8) to a tiny positive
     number.

        (9) The radius in cells for the area in which fluxes are
     computed.  < 1.1 => 3.1.  Can change with TELL.

       (10) = multiplier of max image size to set beam size.  Values
     of 2, 1, 0.5, and 0.25 are allowed.  0 => 2.  Smaller beam images
     are a bit faster, but less accurate in the early Clean cycles.
     The largest beam image used is 2048 on a side.

     Multi-resolution experimental controls are based on
            BeamRatio = (field beam area) / (min beam area)
     See below for more discussion.

       (11) Multi-resolution experimental control: select which field
     to Clean using peak fluxes (in Jy/beam) weighted by
     1 / (BeamRatio)**IMAGRPRM(11).

       (12) Multi-resolution experimental control: decrement the value
     of IMAGRPRM(11) used above by IMAGRPRM(12) each time an non-point
     resolution field is Cleaned until it is 0.

       (13) Multi-resolution experimental control: use gain =
     GAIN * [ {1/BeamRatio} ** IMAGRPRM(13) ]

       (14,15) Multi-resolution experimental control: use
     factor = FACTOR + IMAGRPRM(14) * [ 1 - {BeamRatio} ** IMAGRPRM(15) ]

       (16) Multi-resolution experimental control: use maxpixel
     = MAXPIXEL + IMAGRPRM(16) * (BeamRatio)

        (19) In OVERLAP>= 2 mode, when Cleaning a field with a small
      bright source, it is possible to Clean too deeply.  Then weak
      lumps due to sidelobes of strong sources in other fields are
      treated as sources in the present field.  By the time the
      present field is Cleaned again, these errors become very
      apparent.  This parameter is used to limit the weakest source
      Cleaned in this major cycle to IMAGRPRM(19) times the strongest
      source in this cycle.  The default is the sum of the maximum
      sidelobe outside a radius of 5 pixels and the maximum sidelobe
      outside a radius of MINPATCH pixels.

       (20) In OVERLAP >= 2 mode, the objective function of the
     selected field after it is re-imaged is compared to the objective
     function of the second best field (without re-imaging).  If the
     second best now appears better than the selected field by a
     factor greater than IMAGRPRM(20), then the task will try another
     field. 0 = 1.005.  (Values < 1 are converted to 1/IMAGRPRM(20)
     and, finally, values > 5 => 1.005.)

The MR Clean is an experimental algorithm and has been provided with a
number of "knobs" to adjust its behavior.  All the knobs use the ratio
of the current beam area (BMAJ(field)*BMIN(field)) to the minimum beam
area (R).  These knobs are:

    1. Show some preference to select higher resolution images (lower
       R) for the next image to Clean.  Otherwise a strong point with
       some extended emission will be over Cleaned at low resolution,
       forcing higher resolutions to correct many pixels:
          IMAGRPRM(11) select which field to Clean using peak fluxes
          (in Jy/beam) weighted by 1 / R**IMAGRPRM(11).

    2. Reduce this preference to zero as one Cleans more and more of
       the R > 1 fields:
          IMAGRPRM(12) decrement the initial value of IMAGRPRM(11)
          used above by IMAGRPRM(12) each time an R > 1 resolution
          field is Cleaned until it is 0.

    3. The lower resolution fields may easily over Clean creating zero
       net flux from a mix of negative and positive areas.  These then
       have to be corrected with numerous high resolution Clean
       steps.  To use a lower loop gain for lower resolution:
          IMAGRPRM(13) use gain = GAIN / R ** IMAGRPRM(13)

    4. To avoid over Cleaning with lower resolution, one may also
       Clean each major cycle less deeply with the FACTOR parameter.
       To control FACTOR:
          IMAGRPRM(14,15) use
             factor = FACTOR + IMAGRPRM(14) * (1 - R ** IMAGRPRM(15))

Multi-resolution experimental control limits:
    0 <= IMAGRPRM(11) <= 1.0    not changed by TELL     Try 0.5
    0 <= IMAGRPRM(12) <= 0.1    changed by TELL         Try 0.03
    0 <= IMAGRPRM(13) <= 1.0    changed by TELL         Try 0.5
    0 <= IMAGRPRM(14) <= 1.0    changed by TELL         Try 0.1
    0 <= IMAGRPRM(15) <= 1.0    changed by TELL         Try 0.5
Note that IMAGRPRM(11-15) = 0 causes each Clean to be done on the
field with the highest Jy/point-source-beam with the same GAIN and
FACTOR.

Tasks:
    IMAGR.....Wide-field and/or wide-frequency Cleaning / imaging
              task.
----------------------------------------------------------------
