Program: ANTPAT
Purpose: Calculate beam width (Full Widths at Half Maximum) and
position angle of synthesized beam.
Category: RADIO
File: antpat.c
Author: M.G.R. Vogelaar
Keywords:
APSET= Give antenna pattern set, subsets:
Enter here the name of the antenna pattern optionally
followed by one or more subsets. The subsets must be
2 dimensional. Maximum number of subsets is 1024.
** BOX= Give box in ..... [entire subset]
The data enclosed by this box will be used to estimate
the beam parameters: Full Width At Half Maximum (FWHM)
of major axis, FWHM of minor axis and the position angle
Only the data within the box that belong to the first
maximum of the antenna pattern with a value greater than
or equal to CLIP= will be used in the calculations.
UPSET= Enter other set,(subset(s)) for header update: [NONE]
Besides the header of the antenna pattern itself,
write beam properties also to the header(s) of UPSET=
The same information is written to all subsets of UPSET=
The maximum number of subsets is 1024.
** GRIDS= FWHM's in grids anyway? Y/[N}
If it is possible to convert grids to seconds of arc,
the output will be in arcsecs. If however you want
the output in grids anyway enter GRIDS=Y at the
command line.
OVERLAY= Overlay ellipse(s) in GIDS? Y/[N]
If GIDS displays a set with the same name as APSET=
then you are prompted with this keyword. It is asked
hidden if the names do not match and the keyword is
skipped if GIDS is not in use.
The program will mark the data used in the fit and will
draw the ellipse that corresponds to the fitted beam.
RESCALE= Do you want to rescale the AP? [Y]/N
Only asked if the maximum value in the pattern is not
equal (or very close) to 1.0. If the user responds
with [Y], the AP is rescaled in a way such that this
central value becomes 1.0. In fact application
SCALE is started. You will be asked to enter the
destination set (OUTSET=).
The program continues to fit the input AP.
** CLIP= Enter threshold for first max. in map units:[calculated]
Only the data within BOX= that belong to the first
maximum of the antenna pattern with a value greater than
or equal to CLIP= will be used in the calculations.
The default is the absolute value of the minimum in
BOX=
If you are sure that the first minimum is < 0 at all
positions, it is save to use CLIP=0 to get the maximum
number of data points.
This keyword must be set for all subsets, otherwise the
default is substituted.
** BEAM= Initial estimates for maj.,min. axes: [calculated]
Overrule the calculated initial estimates by specifying
new values for the major and minor axis in arcsecs.
or in grids if you are working in grids.
Note that the beam parameters are always free parameters
in the least squares fit.
** POSANG= Enter in.est. for the PA wrt. Y-axis (deg): [calculated]
Overrule the calculated initial estimate for
the position angle in degrees. The angle needs not to
be corrected for the rotation of the map, so it is always
an angle in degrees with respect to the positive Y-axis.
This parameter can be set to a fixed parameter in the
least squares fit. See remarks at FIXPA=
** FIXPA= Fix PA in fit with value 0 or 90 deg.: Y/[N]
If you want to fix the position angle (PA) at
0 (or 90) degrees, then the axes of the beam will
be fitted as if they were aligned to your grid axes.
** TOLERANCE= Fractional tolerance for the chi square: [0.0]
Fitting is stopped when successive iterations fail
to produce a decrement in reduced chi-squared less
than TOLERANCE= The value cannot be less than a
certain minimum as set by the system. This means that
maximum accuracy can be obtained with TOLERANCE=0.0
** MAXITS= Maximum number of iterations in fit: [50]
If this number is exceeded, no parameters could be
fitted and blanks are written to the output set.
** LAB= Value for mixing parameter: [0.001]
Mixing parameter in the least squares fit function.
LAB= determines the initial weight of steepest descent
method relative to the Taylor method. LAB= should be
a small value (i.e. 0.001).
FITAGAIN= Do you want to fit again? Y/[N]
If there was a fit, the default is to write the
beam parameters to the header and then end the program.
Do you want to fit again? {Y}/N
The fitting procedure could not obtain any parameters.
The default is to rerun the fitting procedure. Now
you are prompted with the keywords
ESTIMATES=, FIXPA=, TOLERANCE=, MAXITS= and LAB=
(all hidden before). The values for these keywords all
have their effect on the fitting procedure.
Description: ANTPAT calculates the synthesized beam by fitting a 2-dim
gaussian to all the data connected -through neighbouring
pixels- to the first maximum i.e. only pixels within BOX=
that have a value greater than CLIP= and are connected to the
maximum are involved in the calculations. The least squares
fit needs a set of initial estimates. We use a moments
method to calculate these estimates. The expression for
the 2-dim gaussian that is used is:
z(x,y) = z0.exp[-{a(x-xc)^2+b(y-yc)^2+2c(x-xc)(y-yc)}]
and ANTPAT tries to make a best fit for the parameters
a, b and c. The amplitude z0 is a fixed parameter with a
value calculated by the moments method. The parameters
a,b and c can be transformed to ellipse parameters.
It is common to fix an ellipse at z(x,y)=z0/2.
The axes and position angle of this ellipse give us the
beam parameters which we are looking for.
Beam parameters are Full Widths at Half Maximum (the major
and minor axes of the ellipse in arcsec) and
a position angle (defined as the smallest angle from
the +M axis -direction of constant longitude- to the
major axis of the ellipse in the direction of the +x axis
(FITS definition). The position angle that is displayed
and written to one or more set headers, is corrected
for the map rotation if the header indicates that
there is such a rotation (map is spatial and 'CROTA'
keyword in header has value unequal to 0).
The errors on the parameters as returned by the least
squares fit are standard errors.
The standard antenna pattern has a maximum at grid
position (0,0) and the value of this maximum is 1.0.
If one of these conditions is not true, a warning is
generated, but the fitting procedure will continue.
However, for a maximum unequal (within a certain range)
to 1, it is possible to rescale the data. Program SCALE
will be started to perform this task.
Results of the fit will be written in the header of the
antenna pattern set at subset level. The parameters can
be found in keywords BMMIN, BMMAJ, BMPA and APSET.
The parameters are only stored if a fit could be
made and a conversion of grids to arcsec is possible.
The position angle is stored in degrees and in APSET we
find the name and subset level of the origin of the data.
You can also write the results to the header of another
set. The name of that set is entered with UPSET=
You can enter a maximum of 1024 subsets to update UPSET=
Notes:
Example:
antpat (start antpat) 24/04/96 16:24:00
ANTPAT APSET=mkap 0
ANTPAT UPSET=
ANTPAT OVERLAY=
====================== ANTPAT =======================
Antenna pattern: mkap FREQ 0 Box: [ -65 -64 62 63 ]
Gridspacing x,y: -79.999920 x 97.181640 (arcsec)
Initial values used for LSQ fit (Moments method):
-------------------------------------------------
Major FWHM: 187.044 (arcsec)
Minor FWHM: 186.851 (arcsec)
Position angle: 93.6941 (degrees)
(wrt. +Y axis)
Results of least squares fit after 8 iterations:
-------------------------------------------------
Major FWHM: 203.789 +/- 2.35715 (arcsec)
minor FWHM: 203.659 +/- 2.2852 (arcsec)
Position angle: 90.2709 +/- 0.0489883 (degrees)
Corrected for a
map rotation of
3.80 deg.
Tolerance in the fit: 0. Mixing factor: 0.001
======================================================
ANTPAT FITAGAIN=y
ANTPAT BEAM=
ANTPAT POSANG=
ANTPAT FIXPA=y
ANTPAT TOLERANCE=
ANTPAT MAXITS=
ANTPAT LAB=
====================== ANTPAT =======================
Antenna pattern: mkap FREQ 0 Box: [ -65 -64 62 63 ]
Gridspacing x,y: -79.999920 x 97.181640 (arcsec)
Initial values used for LSQ fit (Moments method):
-------------------------------------------------
Major FWHM: 186.677 (arcsec)
Minor FWHM: 187.101 (arcsec)
Position angle: 90 (degrees)
(wrt. +Y axis)
Results of least squares fit after 9 iterations:
-------------------------------------------------
Major FWHM: 203.301 +/- 2.39837 (arcsec)
minor FWHM: 204.037 +/- 2.35652 (arcsec)
Position angle: 86.2 +/- 0 (degrees)
Corrected for a
map rotation of
3.80 deg.
Tolerance in the fit: 0. Mixing factor: 0.001
======================================================
ANTPAT FITAGAIN=n
(end antpat) 24/04/96 16:25:18
ANTPAT +++ FINISHED +++
Updates: Mar 26, 1996: VOG, Document created.
Apr 14, 2009: VOG, Removed NINT macro in utils.h