As of Mon Jul 15 17:07:02 2024

FLATN: Re-grid multiple fields and pointings to one image


                                   Input images
INNAME                                Image name (name)
INCLASS                               Image name (class)
INSEQ              0.0      9999.0    Image name (seq. #)
INDISK             0.0         9.0    Image disk drive #
NFIELD             1.0      4096.0 Max number of fields per
NMAPS              1.0             Number of pointings
                                   Output image
OUTNAME                               Image name (name)
OUTCLASS                              Image name (class)
OUTSEQ            -1.0      9999.0    Image name (seq. #)
OUTDISK            0.0         9.0    Image disk drive #
IMSIZE          0.0     16384.0    Output image size in pixels
COORDINA                           Central pixel coordinate
                                   all 0 => use observed
COOTYPE                            Desired projection type
COOINC                             Desired coordinate increment
COOREF                             Desired reference pixel
ROTATE         -180.0      180.0   Rotation to be used (deg)
REWEIGHT        0.0         4.0    (1) Interpolation halfwidth
                                   (2) Minimum fraction of good
                                       pixels required (0->1/3)
WEIGHTIT        0.0                Weight image down by WEIGHTIT
                                   times radius from center in "
EDGSKP                             Skip pixels around the edges
                                   inscribed ellipse also used
OPTYPE                             For mosaics only (NMAPS>1)
                                   compute and output expected
                                   noise ('NOIS') or weight
APARM                              (1) >0 => do 3-D corr.
                                      ONLY for snapshots
                                   (2) Parallactic angle (deg)
                                   (3) Zenith angle (deg)
                                   (4-8) radial scaling parms
                                   (9) Linear scaling
PBPARM                             Beam parameters (NMAPS > 1)
                                   (1) Cutoff; (2) Use (3)-(7)
                                   (3)-(7) Beam shape
NOISE            0.0               Relative uncertainties by
                                   pointing: 0 -> image header
BADDISK          0.         36.    Disks to avoid for scratch


Type: Task
Use: FLATN does an interpolation of a set of images (multiple fields
     produced by IMAGR of multiple pointings) to a single image of
     standard geometry centered on the pointing position of the first
     pointing or a user-specified position.

     Interpolation is done only in the first 2 dimensions.  FLATN will
     interpolate over blanked pixels so that it can fill in small
     blanked regions and handle edges without having to discard image
     area.  Where images overlap, they are averaged with weighting
     that accounts for the location within the pointing and for the
     distance from the center of each field.  If there are multiple
     pointings ("mosaicing') so that NMAPS > 1, the output image is
     corrected for the single-dish beam patterns.  In that case, one
     may compute a noise image (sigma) or a weight image (1/sigma^2)
     instead of an actual image.

     FLATN will search fields nnn through nnn+NFIELD-1 for sequence
     numbers INSEQ through INSEQ+NMAPS-1 where INCLAS=xxxnnn with nnn
     being a 3 digit number (no blanks - typically 001).
  INNAME......The input image name.   Standard defaults.
  INCLASS.....The input image class.  The first 2-3 characters determine
              a base name and the last 4-3 are a numeric field number
              nnn (i.e. ICL001 or IIM012 or IC3245).  Class names for
              higher fields are nnn through nnn+NFIELD-1.  Old style
              names in which the last 2 characters represent the field
              number minus one in extended Hex are also supported.
  INSEQ.......The input image sequence number. <= 0 => 1
  INDISK......The input image disk drive no. 0 => any
  NFIELD......The maximum number of fields imaged (1-4096) for any
  NMAPS.......The number of pointings - using INSEQ numbers INSEQ
              through INSEQ+NMAPS-1.  If NMAPS > 1, the output image
              will be corrected for a primary beam pattern; otherwise
              it is not.  The product of NFIELD * NMAP is limited to
  OUTNAME.....The output image name.  blank => Standard defaults based
              on INNAME.
  OUTCLASS....The output image class.  Standard behavior.
  OUTSEQ......The output image seq. no., 0=> highest unique
              If >0; image will be created if new, overwritten if image
              name exists.
  OUTDISK.....Output disk drive no., 0=> highest with space
  IMSIZE......Output image size in pixels [1=columns, 2=rows].  Default
              is the input image size but you should probably use
              something much larger.  (<= 8192)
  COORDINA....The RA and declination coordinates are found as:
              RA  = abs(CO(1)) + abs(CO(2))/60 + abs(CO(3))/3600
                  if any of CO(1), CO(2), CO(3) < 0: Xpos = -Xpos
              Dec = abs(CO(4)) + abs(CO(5))/60 + abs(CO(6))/3600
                  if any of CO(4), CO(5), CO(6) < 0: Ypos = -Ypos
              The units are standard FITS units (e.g degrees) except
              that right ascensions are in hours of time.
              RA = Dec = 0 => use the Observed RA and Dec (pointing
              position) or if they is 0, use the center of field 1.
              Note that COORDIN of 1-3 is treated as being in hour,
              minutes, and seconds of time even if the axis is not a
              right ascension.
  COOTYPE.....Desired image projection ' ' => same as input
              Allowed values '-SIN','-TAN','-ARC','-STG','-NCP' are
              the familier projective geometries.  Full-sky
              cylindrical geometries '-AIT','-GLS','-MER','-CAR',
              '-MOL', and '-PAR' are also supported.  These geometries
              turn into "oblique" coordinates when the reference
              latitude/declination is not 0.0D0.  You are unlikelt to
              want an oblique system.  But note that RA and DEC both
              0.0 cause the task to take the RA and Dec of the first
              image for projective geometries and the RA of the first
              image with Dec=0.0 for the all-sky coordinates.
  COOINC......Coordinate increment at the reference pixel in arc sec.
              0 -> use that of first input image.  Be careful of sign.
  COOREF......Coordinate reference pixel.  (0,0) -> use the output
              image center.  Need not be in the image or integer in
  ROTATE......Rotation to be used.  Note that 0 is not a default
              telling the task to use the rotation in the first image;
              it is a real value instead.  Use GETHEAD to get the
              first header rotation if desired setting ROTATE=KEYV(1).
  REWEIGHT....Interpolation kernel parameters:
              (1) Half width of the interpolating kernel
                  (1 - 4).  Default = 1
              (2) Minimum fraction of pixels in interpolation kernal
                  area required for non-blanked output.
                  <= 0 or >= 1  => 0.333
  WEIGHTIT....If >0, reduce the weight in each image by WEIGHTIT *
              Radius in arc seconds from the center pixel.  This is to
              give less weight to pixels more affected by non-planar
              affects.  Thus Wt = max (0.0001, 1.0 - WEIGHTIT*radius).
              Note that this is a very stong taper if you are not
              careful and it is applied along with the primary beam
              correction when NMAPS > 1.  NOTE the inscribed ellipse
              operation described with EDGSKP.
  EDGSKP......Omit EDGSKP (or if EDGSKP < 0, -EDGSKP-1) pixels on all
              sides of the input images.  This is to avoid various
              edge effects from damaging the result.  If EDGSKP >= 0,
              the inscribed ellipse of X radius NX/2-EDGSKP and Y
              radius NY/2-EDGSKP is cheked and all points outside it
              are given weight 0.0001.  (EDGSKP=0 -> 5 for the ellipse
              but the whole image is used otherwise.)  To include all
              pixels set EDGSKP=-1.
  OPTYPE......When NMAPS > 1, control of what is computed and output:
              'NOIS'  a noise image based on the assumption that the
                      noise in an image is constant before application
                      of the primary beam correction and is given by
                      NOISE(i) below for pointing i.
              'WEIG'  a weight image given by (1/sigma^2).
              other   a beam corrected, noise weighted average image.
              If NMAPS=1, OPTYPE is ignored.
  APARM.......Transformation parameters:
               (1) = if > 0 then apply 3-D corrections
                     SEE EXPLAIN OHGEO or FLATN
                   This really works well only for snapshots and for
                   fields that are not too far from the pointing
               (2) Parallactic angle for 3-D correction if not
                   already a header keyword. (degrees)
               (3) Zenith angle for 3-D correction if not
                   already a header keyword. (degrees)
               (4-8) Parameters for radial scaling for primary
                     beam effects.
               (4) = Antenna FWHM at nominal sky frequency (deg)
                   0 => no scaling.
               (5) = Fractional bandwidth
               (6-8) C1, C2, C3
                   SEE EXPLAIN FLATN (or OHGEO)
               (9) Linear scaling factor, 0 => 1.0
                   SEE EXPLAIN FLATN (or OHGEO)
  PBPARM......Primary beam parameters used only if NMAPS > 1:
              (1) Lowest beam value to believe: 0 -> 0.1
              (2) > 0 => Use beam parameters from PBPARM(3)-PBPARM(7)
                  Otherwise use default parameters for the VLA (or
                  ATCA where appropriate)
              In FLATN only: if PBPARM(1) > 0 and PBPARM(2) > 0 and
              PBPARM(3) through (7) are all 0, then no primary beam
              correction is made.  All other tasks use the VLA or ATCA
              beam if PBPARM(3) = 0 even though PBPARM(2) > 0.
              (3-7)..For all wavelengths, the beam is described by the
                   1.0 + X*PBPARM(3)/(10**3) + X*X*PBPARM(4)/(10**7) +
                   X*X*X*PBPARM(5)/(10**10) + X*X*X*X*PBPARM(6)/(10**13)
                where X is (distance from the pointing position in arc
                minutes times the frequency in GHz)**2.
                See explain for details
  NOISE.......Expected image noise per pointing.  0 -> check header of
              first field in pointing for ACTNOISE, if missing use 1.
              The absolute scaling affects the output noise or weight
              images but is otherwise not relevant.  This just scales
              one pointing relative to another.  The average value of
              NOISE is used for all pointings in excess of 64 unless
              ACTNOISE is present in those headers.  Note that
              ACTNOISE is written im image headers by IMEAN when it
              succeeds in fitting the true noise of an image.
  BADDISK.....Disks to avoid for the scratch files.


Primary Beam Parameters

     FLATN corrects an image for the primary beam attenuation of
the antennas.  The function used to model the primary beam for normal
VLA frequencies

            F(x) =  1.0
                   + parm(3) * 10E-3  * x
                   + parm(4) * 10E-7  * x*x
                   + parm(5) * 10E-10 * x*x*x
                   + parm(6) * 10E-13 * x*x*x*x
                   + parm(7) * 10E-16 * x*x*x*x*x

where x is proportional to the square of the distance from the
pointing position in units of [arcmin * freq (GHz)]**2, and F(x)
is the multiplicative factor to divide into the image intensity at the
distance parameter x.  For other antennas, the user may read
in appropraite constants in PBPARM(3) through PBPARM(7).  The
flag, PBPARM(2) must be set to a positive number to invoke this
option and PBPARM(3) must not be zero.
     This correction scales with frequency and has a cutoff
beyond which the map values are set to an undefined pixel value GIVEN
in PBPARM(1).  At the VLA frequencies the default cutoff is
                 1.485 GHz     29.8  arcmin
                 4.885 GHz      9.13 arcmin
                15     GHz      2.95 arcmin
                22.5   GHz      1.97 arcmin
and occurs at a primary beam sensitivity of 2.3 percent of the value at
the beam center.  Corrections factors < 1 are forced to be 1.
The estimated error of the algorithm is about 0.02 in (1/F(x))
and thus leads to very large errors for x>1500, or at areas
outside of the primary response of 20 percent.  The cutoff level
may be specified with DPARM(1).

Default values of PBPARM for the VLA are given by Perley's fits:
      0.0738 GHz  -0.897  2.71   -0.242
      0.3275      -0.935  3.23   -0.378
      1.465       -1.343  6.579  -1.186
      4.885       -1.372  6.940  -1.309
      8.435       -1.306  6.253  -1.100
     14.965       -1.305  6.155  -1.030
     22.485       -1.417  7.332  -1.352
     43.315       -1.321  6.185  -0.983
For the ATCA, these are by default:
      1.5 GHz     -1.049   4.238  -0.8473  0.09073  -5.004E-3
      2.35        -0.9942  3.932  -0.7772  0.08239  -4.429E-3
      5.5         -1.075   4.651  -1.035   0.12274  -6.125E-3
      8.6         -0.9778  3.875  -0.8068  0.09414  -5.841E-3
     20.5         -0.9579  3.228  -0.3807  0.0       0.0
For the Karl G Jansky VLA ("EVLA"), the defaults are frequency
dependent.  If the observing frequency is between two tabulated
frequencies, then the beam is computed for each of the tabulated
frequencies and then interpolated to the observing frequency.  The
values used are far too numerous to give here, see EVLA Memo 195,
"Jansky Very Large Array Primary Beam Characteristics" by Rick Perley,
revision dated June 2016.  Obtain it from

                 RICK PERLEY'S (OLD) REPORT

	Polynomial Coefficients from LSq Fit to VLA Primary
	Beam raster scans.

	Functional form fitted:

		1 + G1.X^2 + G2.X^4 + G3.X^6

	where X = r.F,

	and 	r = radius in arcminutes
		F = frequency in GHz.

	Fits were made to 3 percent cutoff in power for 24 antennas.
Poor fits, and discrepant fits were discarded, and the most
consistent subset of antennas had their fitted coefficients
averaged to produce the following 'best' coefficients.

Freq.		G1		G2		G3

0.0738          -0.897E-3       2.71 E-7        -0.242E-10
0.3275          -0.935          3.23            -0.378
1.285           -1.329          6.445           -1.146      *
1.465           -1.343          6.579           -1.186
4.885           -1.372          6.940           -1.309
8.435           -1.306          6.253           -1.100
14.965          -1.305          6.155           -1.030
22.485 (old)    -1.350          6.526           -1.090      *
22.485 (new)    -1.417          7.332           -1.352
43.315          -1.321          6.185           -0.983

	The estimated errors (from the scatter in the fitted
coefficients) are generally very small:

	G1: .003 at all bands except Q (.014)
	G2: .03 to .07 at all bands except Q (.15)
	G3: .01 to .02 at all bands except Q (.04)

	R. Perley  21/Nov/00

* The 1.285 and 22.485 old feed values are not used.

3-D Corrections:

   Corrections can be made for the distortion of an image made by a
coplanar array which is not normal to the field center.  This case
includes snapshots made with the VLA or syntheses made with an
east-west interferometer using u, v and ws in the sine (????-SIN)
projection.  In these cases the array elements are confined to a plane
(or are nearly so) but the normal to this plane is oriented in a
direction other than the center of the image produced.  This will
cause a distortion of the geometry but not of the image.  OHGEO will
correct for this distortion if APARM(1) > 0 and two parameters
("parallactic" angle and "zenith" angle are provided.  These are the
parallactic and zenith angles of the image center.  For east-west
arrays these values are from a "zenith" of the appropriate celestial
pole; for the VLA these are with respect to the instrumental zenith.
   The parallactic and zenith angles can be provided in degrees as
either catalog header keywords 'PARANGLE' and 'ZENANGLE' or as
APARM(2&3) in which case they will be converted into header keywords.
Note: for VLA snapshots task IMAGR can provide the necessary catalog
   The 3D correction is based on the distance from the tangent point
which may be the same as the pointing position (DO3DIMAG false) or
different (DO3DIMAG true in IMAGR).  The coordinate reference pixel
must give the tangent point position.  The x and y coordinates must be
RA and Declination or vice versa or this program will not work
   Note: this correction will not correct for image distortion caused
by a noncoplanar array such as an image made from VLA data consisting
of multiple snapshots or an extended synthesis.

Radial Scaling for Primary Beam Effects.

In synthesis observations the variation of the primary antenna
gain over the observed bandpass can cause the effective
observing frequency to vary radially from the antenna pointing
position.  This will cause a radial variation in apparent image
scale; usually a contraction of the scale with increasing
radius.  A correction can be made for this using parameters
   Note there may also be a constant scale error due to an
incorrect assumed central frequency.  This correction will not
correct for this effect.
   The radial corrections are based on the position offset from the
original pointing center and this information MUST be in the catalog
header.  GETHEAD can obtain these values using keywords 'OBSRA' and
'OBSDEC' to see if non-zero values are present.

   If APARM(4) is larger than zero the a radial scaling is done.
This value is the antenna primary beam FWHM in degrees at the
nomimal sky frequency.  For the VLA (25 m antenna) this is
7.203E8/Freq (Hz).

   This value is the fractional bandpass which is the true
bandpass divided by the nominal frequency.

   These coefficients, called C1, C2 and C3, parameterize the
beam shape.  For a Gaussian beam C1 = 2*log(2)/3 = 0.4621, C2=0
and C3=0.  For a uniformly illuminated circular aperture (a good
approximation for the VLA) C1=0.46, C2=0 and C3=0.58 gives a
good approximation out to a distance of FWHM.

Linear scaling:

   An error in the assumed center frequency of data used to make
a synthesis image will cause a misscaling of the image as
discussed in the previous section.  If the assumed bandpass
shape is incorrect there will be a constant scaling error over
the entire image.  This effect can be corrected in a number of
other tasks (UVADC, IMAGR) and if this correction has already
been applied it should NOT be reapplied here.  This factor is
the ratio of the true centroid frequency to the assumed
   If APARM(9) is greater than 0 then it is used as an overall
scaling factor which is used in addition to any scaling from