AIPS HELP file for FRMAP in 31DEC24
As of Sat Apr 20 0:00:34 2024
FRMAP: Task to build a map using fringe rate spectra
INPUTS
USERID User number - ignored
INNAME Input UV file name (name)
INCLASS Input UV file name (class)
INSEQ 0.0 9999.0 Input UV file name (seq. #)
INDISK 0.0 9.0 Input UV file disk unit #
SRCNAME Source name.
QUAL -10.0 Source qualifier -1=>all
CALCODE Calibrator code ' '=>all
SELBAND Bandwidth to select (kHz)
SELFREQ Frequency to select (MHz)
FREQID Freq. ID to select. .LE.0 =>1
UVRANGE UV range in klambda
0,0 => all baselines
TIMERANG Time range to be selected.
1-4 = start day,hr,min,sec
5-8 = end day,hr,min,sec
0 => timerange of the data
STOKES Stokes type to select.
'RR' or 'LL'; ' '=>'RR'
BIF 0.0 100.0 Selected IF number 0=>1
BCHAN 0.0 2048.0 Lowest channel number 0=>all
ECHAN 0.0 2048.0 Highest channel number 0=>all
CHANNEL -100.0 2048.0 Reference channel number
0 => (bchan + echan)/2
<0 => referencing is not used
SUBARRAY 0.0 1000.0 Subarray, 0=>1
ANTENNAS Antennas to select
BASELINE Baselines with ANTENNAS
See explanation.
DOCALIB -1.0 101.0 > 0 calibrate data & weights
> 99 do NOT calibrate weights
GAINUSE CL (or SN) table to apply
DOPOL -1.0 10.0 If >0 correct polarization.
PDVER PD table to apply (DOPOL>0)
BLVER BL table to apply.
FLAGVER Flag table version
DOBAND -1.0 10.0 If >0 apply bandpass cal.
Method used depends on value
of DOBAND (see HELP file).
BPVER Bandpass table version
SMOOTH Smoothing function. See
HELP SMOOTH for details.
APARM Control information:
1: pre-average interval (sec)
0 => 1/256 of the whole
interval of averaging -
BPARM(3)
-1 => variable depending
upon maximum possible
fringe rate
2: zero padding for FFT
0 => no padding
1 => N zeroes
2 => 2N zeroes etc.
3: no of frequency channels
to pre-average.
4: step at X-axis,
in mili arcsec.
0 => (X-halfwidth)/50
5: step at Y-axis,
in mili arcsec.
0 => (Y-halfwidth)/50
6: halfwidth of rectangle
on the sky in X-direction;
mili arcsec.
0 => is calculated
7: halfwidth of rectangle
on the sky in Y-direction;
mili arcsec
0 => is calculated
8: Position of rectangle
center in X-direction;
mili arcsec
9: Position of rectangle
center in Y-direction;
mili arcsec
10: 0=> find the solution;
>0 => plot the sets of
lines skiping solution.
BPARM More control information:
1: Threshold (in sigmas) in
detection maxima in fringe
rate spectrum.
0 => 4
2: Time interval between
beginnings of interval of
averaging, minutes
0 => interval in TIMERANG
3: interval of averaging,
minutes
0 => interval in TIMERANG
4: expected accuracy,
mili arcsec
0 => is calculated
5: number of lines plotted
0 => all
-1 => nothing to plot
6: minimum number of lines
for considering crosing
(multiply by NSET).
0 => 0.4(*NSET)
7: number of iterations in
elimination of extra lines
0 => 4
8: Number of lines; criteria
of stop itteration (LINES)
0 => 0.6(*NSET)
9: Level of printing;
0 => minimum
1 => middle
2 => max. See explain.
LTYPE -410.0 410.0 Type of labeling: 1 border,
2 no ticks, 3 - 6 standard,
7 - 10 only tick labels
<0 -> no date/time
OUTTEXT Filename in which the list
of found components is
written.
BADDISK 0.0 9999.0 Disks to avoid for scratch
DOTV -1.0 1.0 > 0 Do plot on the TV, else
make a plot file
GRCHAN Graphics channel; 0 => 1
HELP SECTION
FRMAP
Type: Task
Use: To create a fringe rate map of the source.
The data to be used can be selected using a variety of criteria
e.g. Uvrange, Timerange or by selecting data from baselines
determined by the ANTENNAS and BASELINE adverbs. Calibration and
flagging can be applied to the data before the fringe rate
mapping. The data can be averaged over a range of frequency
channels within a given IF as well as over a time interval.
The FFT can be optionally padded with zeroes and is computed
with Hanning weighting.
The fringe rate spectra can be calculated after referencing the
data to a reference frequency channel's data.
The reference channel should be selected on the basis of
a simple structure, pointlike or gaussian. It is a good
idea to use tasks FRPLT or VPLOT before FRMAP to examine the
visibilities of all channels to provide a relevant selection of
the reference channel. Having calculated the fringe rates for
each SETTIMES (baseline-time) as well as the coefficients of
sensitivity of the fringe rate to position of a feature in RA(X)
and declination(Y), we obtain the equations of straight lines
UDOT*X(I) + VDOT*Y(I) = FR(I) describing the position of
component I on the sky. If there is only one component for each
frequency channel its position is determined by intersection of
the straight lines set and it can be determined by a least
square method. Having several components for each frequency
channel we obtain an ambiguity in the crossing lines.
The components position can be determined in this case by
finding the places of highest density of crossing lines.
(Details can be read in Giuffrida,T.S, 1977 PH.D. thesis MIT;
and in Walker R.C. Astr. J. v86, 9,1323, 1981). The program
plots the straight lines on the TV or prepares a plot file.
Then the program determines the positions of higher density of
crossing lines. The coordinates in RA and DEC of the found
components are written in an output file.
Adverbs:
USERID.....Input file user number. Ignored.
INNAME.....Input UV file name (name). Standard defaults.
INCLASS....Input UV file name (class). Standard defaults.
INSEQ......Input UV file name (seq. #). 0 => highest.
INDISK.....Disk drive # of input UV file. 0 => any.
SRCNAME....Source name. If the data is a multi-source file
SRCNAME should be specified. Apparent RA and DEC are taken
from SU table. If the data is a single source file no
source name need be specified. Apparent RA and DEC are
colculated. The calculation's accuracy is better 10^(-6).
QUAL.......Only sources with a source qualifier number in the
SU table matching QUAL will be used if QUAL is not
-1.
CALCODE....Calibrators may be selected on the basis of the
calibrator code:
' ' => any calibrator code selected
'* ' => any non blank code (cal. only)
'-CAL' => blank codes only (no calibrators)
anything else = calibrator code to select.
NB: The CALCODE test is applied in addition to the
other tests, i.e. CALSOUR and QUAL, in the
selection of sources for which to determine
solutions.
SELBAND....Bandwidth of data to be selected. If more than
one IF is present SELBAND is the width of the
first IF required. Units = kHz, 0=> all
SELFREQ....Frequency of data to be selected. If more than
one IF is present SELFREQ is the frequency of the
first IF required. Units = MHz, 0=> all
FREQID.....Frequency identifier to select (you may determine
which is applicable from the OPTYPE='SCAN' listing
produced by LISTR. If either SELBAND or SELFREQ
are set their values overide that of FREQID,
however setting SELBAND and SELFREQ may occasionally
result in an ambiguity, in which case the task will
request that you use FREQID.
UVRANGE....Range (min, max) of projected baselines to include
0,0 => all baselines (units: klamda)
TIMERANG...Time range of the data to be selected. In order:
Start day, hour, min. sec,
end day, hour, min. sec. Days relative to ref. date.
0 => time range of the data
STOKES.....The desired Stokes type of the output data: ' ' => RR
'I','V','Q','U','IQU','IQUV','IV','RR','LL','RL',
'LR','HALF' (=RR,LL), 'FULL' (=RR,LL,RL,LR)
BIF........Selected IF to map. 0=>1.
Only one IF can be selected. So EIF is fixed to equal BIF.
BCHAN......First channel to select. 0=>all.
ECHAN......Highest channel to select. The channels averaging
within this channel range is set by APARM(3).
CHANNEL....CHANNEL sets the reference channel number.
If CHANNEL = 0 then reference channel number is
equal (bchan + echan)/2
If CHANNEL < 0 referencing is not used. This option
can be used in the case of continuum sources for
estimating the error of the source coordinates and
when there is a problem to find a channel with
simple structure. The time of averaging can be
limited in this case by frequency unstability of
local oscilators.
SUBARRAY...Subarray number to select. 0=>all.
ANTENNAS...A list of the antennas forming the baselines.
If any number is negative then all antennas listed
are NOT to be used and all others are.
BASELINE...Baselines between antennas named in ANTENNAS and
those named in BASELINE are selected..
There are four possible combinations of ANTENNAS
and BASELINE:
1. ANTENNAS = 0; BASELINE = 0.
All possible baselines are selected.
2. ANTENNAS <>0; BASELINE = 0.
a)All ANTENNAS > 0
Baselines between antennas named in
the ANTENNAS list are selected;
b)Some ANTENNAS < 0
Baselines between antennas named in
the ANTENNAS list are DE-selected;
3. ANTENNAS = 0; BASELINE <> 0.
a)All BASELINE > 0
Baselines between antennas named in the
BASELINE list and any antenna are selected.
b)Some BASELINE < 0
Baselines between antennas named in the
BASELINE list and any antenna are DE-selected.
4. ANTENNAS <> 0; BASELINE <> 0.
a)All ANTENNAS>0; All BASELINE>0
Baselines between antennas named in ANTENNAS
and those named in BASELINE are selected.
b)Some ANTENNAS<0 .OR. Some BASELINE<0
Baselines between antennas named in
ANTENNAS and those named in BASELINE
are DE-selected.
DOCALIB....If true (>0), calibrate the data using information in the
specified Cal (CL) table for multi-source or SN table for
single-source data. Also calibrate the weights unless
DOCALIB > 99 (use this for old non-physical weights).
GAINUSE....version number of the CL table to apply to
multisource files or the SN table for single
source files. 0 => highest.
DOPOL......If > 0 then correct data for instrumental polarization as
represented in the AN or PD table. This correction is
only useful if PCAL has been run or feed polarization
parameters have been otherwise obtained. See HELP DOPOL
for available correction modes: 1 is normal, 2 and 3 are
for VLBI. 1-3 use a PD table if available; 6, 7, 8 are
the same but use the AN (continuum solution) even if a PD
table is present.
PDVER......PD table to apply if PCAL was run with SPECTRAL true and
0 < DOPOL < 6. <= 0 => highest.
BLVER......Version number of the baseline based calibration
(BL) table to appply. <0 => apply no BL table,
0 => highest.
FLAGVER....Specifies the version of the flagging table to be
applied. 0 => highest numbered table. <0 => no flagging
to be applied.
DOBAND.....If true (>0) then correct the data for the shape of the
antenna bandpasses using the BP table specified by BPVER.
The correction has five modes:
(a) if DOBAND=1 all entries for an antenna in the table
are averaged together before correcting the data.
(b) if DOBAND=2 the entry nearest in time (including
solution weights) is used to correct the data.
(c) if DOBAND=3 the table entries are interpolated in
time (using solution weights) and the data are then
corrected.
(d) if DOBAND=4 the entry nearest in time (ignoring
solution weights) is used to correct the data.
(e) if DOBAND=5 the table entries are interpolated in
time (ignoring solution weights) and the data are then
corrected.
BPVER......Specifies the version of the BP table to be
applied (if DOBAND > 0.
0 => highest numbered table.
<0 => no bandpass correction to be applied.
SMOOTH.....Specifies the type of spectral smoothing to be applied to
a uv database . The default is not to apply any smoothing.
The elements of SMOOTH are as follows:
SMOOTH(1) = type of smoothing to apply: 0 => no smoothing
To smooth before applying bandpass calibration
1 => Hanning, 2 => Gaussian, 3 => Boxcar, 4 => Sinc
To smooth after applying bandpass calibration
5 => Hanning, 6 => Gaussian, 7 => Boxcar, 8 => Sinc
SMOOTH(2) = the "diameter" of the function, i.e. width
between first nulls of Hanning triangle and sinc
function, FWHM of Gaussian, width of Boxcar. Defaults
(if < 0.1) are 4, 2, 2 and 3 channels for SMOOTH(1) =
1 - 4 and 5 - 8, resp.
SMOOTH(3) = the diameter over which the convolving
function has value - in channels. Defaults: 1,3,1,4
times SMOOTH(2) used when input SMOOTH(3) < net
SMOOTH(2).
APARM......(1) sets the pre-average time interval
to be used before the FFT. Vector averaging
is performed.
If APARM(1) = 0 then the pre-average time interval
is equal 1/256 of the averaging interval - BPARM(3)
IF APARM(1) = -1 then variable pre-average times are
calculated for a given set depending upon maximum
possible fringe rate. This dynamical change of a pre-
average time minimises the computing time but has
problem of correct determination of sigma because
the spectral components occupy the
whole spectral window and it complicates determination
of the noise. So using dynamical pre-averaging it is
useful to decrease the threshold of spectral line
discrimination (BPARM(1)). It is recomended to avoid
using the dynamical pre-averaging if possible.
Number of data points (with unzero weights) in the
averaging interval for a given baseline-time has to be
more than half of N = BPARM(3)/(pre-avg time).
If number of actual data points at the average interval
(BPARM(3)) is less than 512 the pre-avg time can be
choosen actual pre-avg. time.
(2) defines the zero padding to be used in the FFT.
0=> no padding; 1=> N zeroes added;
2=> 2N zeroes added etc.
(3) sets the number of channels to be pre-averaged for
each FFT. The channel range over which this averaging
takes place is defined by BCHAN and ECHAN.
(4) step in X-axis (RA), in milli arcsec.
0 => (X-halfwidth)/50
(5) step in Y-axis (DEC), in milli arcsec.
0 => (Y-halfwidth)/50
(6) Halfwidth of rectangle on the sky in X-direction;
milli arcsec. 0 => is calculated
The mapping window is limited by rate of change of
fringe rate during the averaging time
and as a result the signal is smeared.
The smearing is greater for the more
distant components. The sizes of the window
depend upon the time averaging and the geometry
of the interferometers.
(7) Halfwidth of rectangle on the sky in Y-direction;
mili arcsec. 0 => is calculated.
(8) Position offset of rectangle center in X-direction;
in mili arcsec.
(9) Position offset of rectangle center in Y-direction;
in mili arcsec
(10) If zero the program provides both the
plotting of the lines' set and the solution for the
components by finding the places of highest density
of the lines and applying a least square method.
If >0 the program provides the plotting of the
lines' set only providing opportunity to the user
to resolve components himself. This last option
saves computing time.
BPARM......(1) Threshold (in sigmas) in detection maxima in
fringe rate spectrum. 0 => 4. See explanation of
APARM(1).
(2) Time interval between beginning of each averaging
interval, minutes
0 => interval in TIMERANG.
(3) Averaging interval, minutes
0 => interval in TIMERANG.
(4) The map's accuracy used in criteria of terminating
of deleting lines in the mapping.
mili arcsec. 0 => calculated
(5) number of lines plotted.
0 => all lines are ploted; -1 => nothing is plotted
(6) minimum number of lines for considering
crosing (multiply by NSET) a given rectangle.
0 => 0.4(*NSET)
(7) number of iterations in elimination of extra
lines; 0 => 4
(8) Number of lines in criteria of itterations stop;
If the number of the lines crossing a given
rectangular cell is bigger than this parameter
the line giving the biggest deviation from the
solution is eliminated. This process is terminated
when the number of crossing lines is equal to this
parameter (*NSET). 0 => 0.6(*NSET)
(9) Level of printing.
0 => minimum.
The numbers of a current time interval, baseline
and channel are printed;
1 => medium.
In addition to mimimum level the information about
rectangular cells with maximum crossing lines is
given. So numbers of a set (combination of baseline
and time), components, and corresponding fluxes are
printed together with coordinates of the rectangular
cell and solution for position of the feature are
printed.
2 => maximum.
In addition to medium level equations
of lines for each set are printed.
LTYPE......Labelling type, see HELP LTYPE for details:
1 = border, 2 = no ticks, 3 or 7 = standard, 4 or 8 =
relative to ref. pixel, 5 or 9 = relative to subimage
(BLC, TRC) center, 6 or 10 = pixels. 7-10 all labels
other than tick numbers and axis type are omitted.
Less than 0 is the same except that the plot file
version number and create time are omitted.
Add n * 100 to alter the metric scaling.
OUTTEXT....The name of a disk file into which the list of founded
components is written.
BADDISK....A list of disks on which scratch files are not to
be placed. This will not affect the output file.
DOTV.......> 0 => plot lines directly on the TV device, otherwise
make a plot file for later display on one or
more devices (including the TV if desired).
GRCHAN.....Graphics channel (1- 7) to use for line drawing.
0 => 1
EXPLAIN SECTION
FRMAP: Task to produce the map of the source using the fringe rates.
Documentator: L.R. Kogan
Related programs: FRPLT
Fringe rates are determined precisely using three steps.
The first one uses criteria of maximum amplitude in the fringe
rate spectrum and discrimination of the features with amplitu-
des less than a selected threshold. The value of this threshold
is equal CO*SIGMA. Sigma is calculated as an average value of
the spectrum. CO is a coefficient which is selected by BPARM(1).
A large value of this coefficient can lead to missing some
features; Small value can produce some false features. The
compromise for the coefficient is between 2 and 5.
The second step in fringe rate determination is based on fitting
amplitudes, fringe rates and phases of features with measured
visibilities as a function of time. Zero points are excluded
from the fitting. This exclusion suppress the false maxima
occured due to lack of data in some time points. The new
amplitudes of features are compared again with the threshold and
false maxima are discriminated against.
The final solution for fringe rates (the third step) is found by
non linear least square method.
Having found fringe rates for all given baselines and all given
times - SETTIMES, the program maps each frequency channel or
group of pre-averaged channels separately. The selected
rectangular window in the picture plane (APARM(6) - APARM(9)) is
devided by number of small rectangular cells. The size of these
cells is determined by expected angular resolution and can be
selected by user (APARM(4), APARM(5)) or calculated.
The program finds the cells which are intersected by the
number of lines larger than the threshold setting by user. This
limiting number of lines = BPARM(6)* SETTIMES, where SETTIMES
is number of sets (baselines-times) and is recomended to be
about (0.5 - 1.0)*SETTIMES. If there are several close cells
intersected by the number of lines larger than the threshold
then the program finds the cell with maximum number of crossing
lines (in this cluster of cells) and eliminates the remainder.
Having found the cells with maximum lines' density the program
applys least square method to determine the components'
position. The least square is repeated several times with
elimination of a line giving maximum deviation from the
solution on each iteration. The iteration process is terminated
if the number of crossing lines is less the selected limit
BPARM(8), the number of iterations is bigger than a given limit
BPARM(7), or the given accuracy BPARM(4) is achieved. The final
list of components found is printed in the ouput file for each
frequency channel or for each group of preaverage channels.