AIPS HELP file for FLATN in 31DEC24
As of Thu Apr 25 5:21:43 2024
FLATN: Re-grid multiple fields and pointings to one image
INPUTS
Input images
INNAME Image name (name)
INCLASS Image name (class)
INSEQ 0.0 9999.0 Image name (seq. #)
(specify)
INDISK 0.0 9.0 Image disk drive #
NFIELD 1.0 4096.0 Max number of fields per
pointing
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
('WEIG').
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
HELP SECTION
FLATN
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).
Adverbs:
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
NOTE THAT THIS DEFAULT IS DIFFERENT FROM USUAL.
INDISK......The input image disk drive no. 0 => any
NFIELD......The maximum number of fields imaged (1-4096) for any
pointing.
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
1048576.
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
value.
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
position.
(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
function:
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)
X*X*X*X*X*PBPARM(7)/(10**16)
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.
EXPLAIN SECTION
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
http://library.nrao.edu/evla.shtml
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
keywords.
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
properly.
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
APARM(4-8).
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.
APARM(4)
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).
APARM(5)
This value is the fractional bandpass which is the true
bandpass divided by the nominal frequency.
APARM(6-8)
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.
NOTE: THIS CORRECTION CAN GIVE VERY VERY WRONG ANSWERS OUTSIDE
OF THE 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
frequency.
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
APARM(4-8).