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