AIPS HELP file for SCMAP in 31DEC24
As of Sat Jul 27 8:40:03 2024
SCMAP: Imaging plus self-calibration
INPUTS
INNAME Input UV data (name)
INCLASS Input UV data (class)
INSEQ Input UV data (seq. #)
INDISK Input UV data disk drive #
OUTNAME Output image name
OUTSEQ -1.0 9999.0 Output image seq. no.
OUTDISK Output image disk drive #
OUT2NAME Output UV file name
OUT2CLAS Output UV file class
OUT2SEQ -1.0 9999.0 Output UV file seq. #
OUT2DISK 0.0 9.0 Output UV file disk drive #
Imaging info
CELLSIZE 1.E-12 (X,Y) size of grid in asec
IMSIZE 0.0 4096. Image size (power of 2)
SHIFT (X,Y) image shift in asec
NOT a "3D" shift.
UVTAPER 0. (U,V) Gaussian taper
units are kilo-lambda
UVRANGE 0. Min & max baseline (klambda)
UVWTFN UV dist. weight function
blank => uniform
UVSIZE 0. Array size for doing uniform
weights. 0 -> actual field
size. ??
ROBUST Robustness power: -4 -> pure
uniform weights, 4 => natural
UVBOX 0. 128. Additional rows and columns
used in weighting.
UVBXFN Box function type when UVBOX
> 0. 0 -> 1 round pill box.
ROTATE Rotate image CCW from N by
ROTATE degrees
ZEROSP 0-spacing fluxes and weights
XTYPE 0. 10. Conv. function type in x
default spheroidal
YTYPE 0. 10. Conv. function type in y
default spheroidal
XPARM Conv. function parms for x
YPARM Conv. function parms for y
Cleaning info
GUARD -1.0 0.9 x,y guard band fractional
radius
NBOXES 0.0 50.0 Number of boxes for CLEAN
CLBOX -2.0 4096.0 Four coordinates for each box
BOXFILE Input Clean boxes
OBOXFILE * Output file for final Clean
boxes
IM2PARM Yet more parameters:
(1) Auto boxes: allowed #
(2) : island level
(3) : peak required
(4) : limit wrt max
(5) : extend boxes
(6) : edge skip
IM2PARM ? Yet more parameters:
? (1) Auto boxes: allowed #
? (2) : island level
? (3) : peak required
? (4) : limit wrt max
? (5) : extend boxes
? (6) : edge skip
GAIN * 0.0 2.0 CLEAN loop gain
FLUX * Minimum CLEAN component (Jy)
MINPATCH * 0.0 Min. BEAM half-width in AP.
NITER * 0.0 Maximum # of CLEAN components
BMAJ * -999.9 FWHM(asec) major axis CLEAN
* restoring beam.
BMIN * -999.9 FWHM(asec) minor axis CLEAN
* restoring beam.
BPA * -360.0 360.0 CLEAN beam position angle
FACTOR * -5.0 5.0 Speedup factor see HELP
MAXPIXEL * 0.0 500000.0 Maximum pixels searched in
* each major cycle.
CMETHOD Modeling method:
'DFT','GRID',' '
Self cal info
NMAPS * Number of self-cal loops.
SMODEL Initial model, 1=flux,2=x,3=y
REFANT * Reference antenna
SOLINT * Solution interval (min)
APARM Control parameters
1=min. no. antennas
2 >0 => normalize gain
3 > 0 => avg. RR,LL
5 > 0 => avg. IFs.
6=print level, 1=some
7=soln SNR cutoff (0=>5)
8=SIGMA (see HELP SCMAP)
< 0 allow negative CCs
9=Edit averaging time
10=Amplitude smoothing time
SOLTYPE * Soln type,' ','L1','GCON',
* 'R', 'L1R', 'GCOR'
SOLMODE * Soln. mode: 'A&P','P','P!A',
* 'GCON'
SOLCON * Gain constraint factor.
ANTWT * Ant. weights (0=>1.0)
GAINERR * Std. Dev. of antenna gains.
WTUV * Weight outside full weight
range in self-cal
WEIGHTIT * 0.0 3.0 Modify data weights function
DOCALIB -1.0 101.0 > 0 calibrate data & weights
> 99 do NOT calibrate weights
GAINUSE 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
OUTFGVER 0.0 Output FG 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.
DOTV * -16.0 16.0 Display residuals on TV ?
0 -> no, 1 -> after each
major cycle and each full
Clean, -1 only after each
full Clean. If you can, do
at least -1.
LTYPE -410. 410. Label TV plots (type of label
with 0, 1 => do not label)
DOWEIGHT * 0.0 Rescale weights by DOWEIGHT
for editing display only
DOTWO * -1.0 1.0 True => do second observable
plot of main baseline for
display only
BADDISK -1.0 1000.0 Disks to avoid for scratch.
BPARM Subarray weight factors
CPARM Subarray ref. ant.
HELP SECTION
SCMAP
Type: Task
Use: Self calibration loop.
This task is very similar to SCIMG except that SCIMG allows the
option of imaging with multiple fields.
This task will do multiple iterations of self-calibration and imaging
optionally starting with a one component model (SMODEL). Each
iteration consists of 1) a visibility based imaging and CLEAN
deconvolution, 2) determination of the appropriate number of CLEAN
components and self-calibration uvrange, and 3) self-calibration of
the visibility data based on the new model. A final
imaging/deconvolution is then done on the final uvdata.
The products of this task are a dirty beam, a CLEAN image and
a calibrated set of uv data.
Interactive data editing is now available as well. Both the
calibrated input data and the residual data are displayed. The former
is used for editing. This forces the task to run as an interactive
task; the AIPS session that started it is frozen until SCMAP finishes.
If you need to TELL SCMAP something, you must use a second interactive
AIPS session and set NUMTELL to the SCMAP AIPS number. This nuisance is
one of the reasons why we recommend using at least the TV option at the
self-cal loop point (DOTV = -1).
Adverbs:
INNAME.....Input UV data file (name). Standard defaults.
This should be a single source file with all prior
calibration and editing done..
INCLASS....Input UV data file (class). Standard defaults.
INSEQ......Input UV data file (seq. #). 0 => highest.
INDISK.....Input UV data file disk drive #. 0 => any.
OUTNAME....Output image name. Standard defaults.
There will be output ICL001 and IBM001 images.
The output CLEAN image will be used during
execution as the residual image.
OUTSEQ.....Output sequence number.
OUTDISK....The disk drive # of output images. 0 => highest
with space (note: map and Beam go on same disk.
OUTSEQ.....Output sequence number.
OUT2NAME...Output UV file name (name). Standard defaults.
The output uv data file is used as a scratch file
during execution.
OUT2CLASS..Output UV file name (class). Standard defaults.
OUT2SEQ....Output UV file name (seq. #). 0 => highest unique
OUT2DISK...Disk drive # of output UV file. 0 => highest
disk number with space
The following control imaging:
CELLSIZE...(X,Y) pixel separation in asec.
IMSIZE.....(X,Y) The desired size of the CLEAN image; must be
a power of 2.
SHIFT......(X,Y) shift of map center from phase center in
asec. Map center = Phase center + shift. If X>0
& Y>0, source shifts to south-west (down & right).
NOTE: SHIFT(1) and SHIFT(2) are not strictly
a shift in RA and Dec. The effect of SHIFT(1) on
the RA of the map center is roughly
SHIFT(1)/COS(Dec).
If the UV data have been rotated then SHIFT(1) and
SHIFT(2) refer to X and Y in the new coordinate
system.
THE DO3DIMAG OPTION OF IMAGR IS NOT SUPPORTED BY SCMAP.
UVTAPER....(U,V) Gaussian taper (kilo-lambda) at 30 percent level
UVRANGE....(Minimum,Maximum) baseline (kilo-lambda) in map.
Note: this value is used only in imaging. The uv
range used in self-calibration is set by the task.
UVWTFN.....Weighting function of (u-v) plane in 2 character
code. If the first character is N use "natural"
weighting (no variation due to local density),
otherwise use "uniform" weighting (weights are
modified by local density of samples - first letter
C - or weights under control of UVSIZE, UVBOX,
UVBXFN, and ROBUST). If the second character is
the letter O, all weights are set to one, and if
the second letter is V, all weights are set the
their fourth root, before any use is made of them.
UVSIZE.....Size of the array used to count samples for uniform
weighting. Does not have to be a power of two and
can be smaller than or bigger than the image size.
The default is the size of the first output image.
ROBUST.....Briggs' "robustness" parameter. "Uniform" weights
are tempered by a constant being added to the local
density of weights. ROBUST = -4 is nearly pure
uniform weighting, ROBUST = +4 is nearly pure
natural weighting. Use of this option requires a
second array in the "AP" memory and may therefore
force the data to be sorted. The option is turned
off if ROBUST < -7 and uniform weighting is turned
off is ROBUST > 7. See HELP ROBUST.
UVBOX......(U,V) box size for weighting. This is the support
radius over which a sample is counted. I.e., the
sample or its weight is counted over an area
2*UVBOX+1 cells on each side in the UV plane, where
the UV cell size is (after correcting units) given
by 1 / (UVSIZE(i) * CELLSIZE(i)).
UVBXFN.....If UVBOX > 0, UVBXFN controls how the samples are
counted as a function of u and v (UVBXFN < 0) or of
radius (UVBXFN > 0). In the latter case, the
function is 0 for radius > UVBXFN. Functions are
pill box, linear, exponential, and Gaussian for
ABS(UVBXFN) = 1-4, resp. 0 -> 1. See HELP UVBXFN.
ROTATE.....Rotation angle to be applied in degrees.
ZEROSP.....(1)= zero spacing flux density for the
polarization being processed. Zero spacing flux is
placed at the center of image.
(2)= FWHM size of major axis for Zero spacing flux
component (in arc seconds).
(3)= FWHM size of minor axis for Zero spacing flux
(4)= Position angle (north through east, degrees)
If (2) is zero, source is assumed bigger than
image.
(5)= the weight for zero spacing flux.
XTYPE......Convolution function type in X-direction
1=Pill-box, 2=exponential, 3=Sinc, 4=Exp*Sinc,
5=Spheroidal, 6=exp*BESSJ1(x)/x.
<= 0 or > 5 -> 5.
YTYPE.....Convolution function type in Y-direction
XPARM.....Array containing parameters for XTYPE.
See HELP UVnTYPE when n=convolution type.
YPARM.....Array containing parameters for YTYPE.
GUARD.....Fraction of the x and y radius for which uv samples
are not allowed. < 0 => just enough to avoid
mathematical errors in the convolution.
0 => 0.3 * SQRT(taper weight at 0.3 from edge).
The following control CLEANing:
NBOXES.....Number (<=50) of rectangular search boxes to search on the
first field; the Clean window in all other fields is given
by FLDSIZE. 0 => use FLDSIZE to determine windows on
field 1.
CLBOX......A 4x50 array with the parameters of each box.
0 => use window specified in FLDSIZE.
CLBOX(1,i)=-1 indicates a circle of radius CLBOX(2,i)
pixels centered on (CLBOX(3,i), CLBOX(4,i)).
CLBOX(1,i) >= 0 indicates a rectangular box. NOTE: CLBOX
is not used to determine the size of the image to be made;
IMSIZE or FLDSIZE must set the size of the image.
BOXFILE....Input text file used to simplify the specification of large
numbers of numbers of Clean boxes.
Leading and trailing blanks from all lines in the text
file are discarded, so "column 1" below means the first
non-blank column in the card.
To set Clean boxes, specify one box per line, as
field blc-x blc-y trc-x trc-y (5 integers) e.g.
1 200 205 220 222
1 230 232 240 241
1 100 100 130 121
....
or circular "boxes" as
field -1 radius center-x center-y (5 ints) e.g.
001 -1 10 210 214
001 -1 5 235 237
....
Column 1 must contain a numeric character (part of the
field number); otherwise the line is treated as some
other sort of line. Note that SCMAP only allows field 1
but the 1 must still be specified.
OBOXFILE...Output text file to record the Clean boxes used. Each time
a TV REBOX or TVBOX is selected the file is rewritten (as
the TV interaction ends) with all of the Clean boxes
currently in force for all fields
IM2PARM....Even more SCMAP parameters (others used by IMAGR ignored):
Auto-Clean boxing (can be changed by TELL):
(1) IMAGR can create Clean boxes automatically. In
OVERLAP 2 mode it will do this only in the facet
about to be Cleaned. In OVERLAP < 2, it looks at
every facet at each major cycle. It will find no
more than the strongest IM2PARM(1) boxes each time
it looks. <= 0 => don't do. Limit 50.
(2) The auto-boxing starts by finding islands of
emission > IM2PARM(2) * rms in the residual image.
This defines the size of the box if it is
accepted. (0 -> 3.0)
(3) A box can only be accepted if its peak brightness
is > IM2PARM(3) * rms in the residual. A box is
also accepted only if the peak in it is not
already in a Clean box.
< IM2PARM(2) -> IM2PARM(2) + 2.0
(4) A box is also only accepted if its peak brightness
is > IM2PARM(4) * maximum residual in the whole
image. < 0.01 OR > 0.9 -> 0.1
(5) The box determined by the island may be extended
outward in all directions by IM2PARM(5) pixels.
< -1 => 1. Note that -1 means compressed by 1 in
radius or in all directions for rectangles.
(6) The residual image is examined only in an ellipse
(circle if IMSIZE(1) = IMSIZE(2)) of radius in X
of IMSIZE(1)/2 - IM2PARM(6) and in Y of
IMSIZE(2)/2 - IM2PARM(6). <= 0 -> 5
GAIN.,.....The CLEAN loop gain. 0 => 0.10.
Can be changed by TELL.
FLUX......Stop CLEAN when abs(resid. image max) < FLUX (Jy)
IF FLUX < 0 then Clean stops at first negative
Clean Component. Can be changed by TELL.
SCMAP may lower this values and in general uses 1.0
times the previous RMS residual unless a lower value
has been set.
MINPATCH..Minimum half width of the portion of the beam
which is used in the AP minor CLEAN.
Can be changed by TELL.
NITER.....CLEAN iteration limit. This is an upper limit as
each CLEAN may stop prior to this limit. The final
CLEAN continues until NITER CLEAN components are
found. Can be changed by TELL.
0 => 200
BMAJ......The FWHM (asec) major axis of the restoring beam.
If 0; value obtained from fitting to the beam.
Can be changed by TELL
8/14/2019: If BMAJ>0 and BMIN>0, the residual image will be
convolved with a Gaussian to make the apparent resolution
BMAJ x BMIN @ BPA (if possible). The residual image will
also be multiplied to make its units Jy/beam of the user
requested beam.
BMIN......The FWHM (asec) minor axis of the restoring beam.
Can be changed by TELL.
BPA.......The position angle in the unrotated image of BMAJ.
Can be changed by TELL.
FACTOR....FACTOR>0 causes deeper CLEAN in each major cycle,
speeding CLEAN, maybe "eating" extended structure.
FACTOR=0 => the normal Clark CLEAN. FACTOR=-0.3 is
good for deep CLEANs of extended structure.
Can be changed by TELL.
MAXPIXEL..The maximum number of pixels that are searched
for components inside the ``AP'' in each major
cycle. < 3000 => 20050. This number affects the
cpu usage significantly. Too many causes the task
to search over many points it will never use. Too
few causes the task to do many more small major
cycles, also at great expense. Use this with great
caution, but big wins are possible using larger
sizes on very large cleans.
CMETHOD...This determines the method used to compute the
model visibility values.
'DFT' uses the direct Fourier transform, this
method is the most accurate.
'GRID' does a gridded-FFT interpolation model
computation.
' ' allows the program to use the fastest
method.
Can be changed by TELL: once set to 'DFT' it can
no longer be changed, however.
The following control self-calibration:
NMAPS......Number of self-calibration loops.
SMODEL.....A single component model to be if SMODEL(1)>0
SMODEL(1) = flux density (Jy)
SMODEL(2) = X offset in sky (arcsec)
SMODEL(3) = Y offset in sky (arcsec)
SMODEL(4) = Model type:
0 => point model (others NYI)
REFANT.....The desired reference antenna for phases.
SOLINT.....The solution interval (min.)
0 => data interval which may or may not be a good
idea. SCMAP doubles SOLINT when(if) it switches
from phase only to amp & phase solutions.
APARM......Task enrichment parameters:
APARM(1)...Minimum number of antennas allowed for a solution.
< 3 => 4.
APARM(2)...If >0 then constrain the mean gain modulus of the
calibration applied to be unity.
APARM(3)...If > 0 then average RR, LL.
APARM(5)...If > 0 then make a combined solution for the IFs;
if <= 0 then make separate solutions.
APARM(6)...Print flag, 0=none, 1=time,some info including the antenna
signal to noise ratio, 2=lots.
APARM(7)...The minimum allowed solution signal-to-noise ratio. 0 => 5
APARM(8)...SIGMA. Each CLEAN can be restarted using a subset of the
components from the previous CLEAN. All merged components
brighter than SIGMA*(residual_RMS) will be reused. 0 => 10
If SIGMA < 0, then negative components will be allowed in
the solutions and ABS(SIGMA) used for the cutoff. In
this case, all components will be used in the self-cal.
Only those components greater in absolute value than
sigma*(residual RMS) will be used to start the next Clean.
APARM(9)...Averaging time used when data are read into the interactive
editing tool in minutes. <= 0 => SOLINT.
APARM(10)..Amplitude solutions may be box-car smoothed wrt the phase
solutions by APARM(10) minutes.
SOLTYPE....Solution type:
' ' => normal least squares,
'R ' => as ' ' with robust iteration
'L1 ' => L1 solution; a weighted sum of the moduli
of the residuals is minimized.
The computed gain solutions are less
influenced by wild data points, but there
is some loss of statistical efficiency.
See [F.R. Schwab, VLA scientific Memo #136]
for further details.
'L1R ' => as 'L1' with robust iteration
'GCON' => least squares which may include gain
constraint.
'GCOR' => as 'GCON' with robust iteration
The robust versions iterate the solution, discarding data
that does not fit the current solution well enough. They
should be less disturbed by bad data, but will be slower.
SOLMODE....Solution mode:
'A&P ' => amplitude and phase.
'P ' => phase only
'P!A ' => phase only (no amplitude information)
'GCON' => amplitude and phase with constraints on
amplitude. This mode requires setting
SOLTYPE='GCON', uses GAINERR and
SOLCON may be used.
' ' => start with phase only and switch to amp and
phase.
SOLCON.....Gain constraint factor; a value larger than 0 will increase
the strength of the amplitude constraint in gain
constrained solution with SOLMODE='GCON'
ANTWT......Antenna weights. These are additional weights to be
applied to the data before doing the solutions, one per
antenna. Use PRTAN to determine which antenna corresponds
to each antenna number. 0 => 1.0
GAINERR....Estimates of the standard deviation of the modulus of the
gains for each antenna. These are used ONLY if SOLMODE and
SOLTYPE='GCON'. The solution will attempt to make the
standard deviation of the modulus of the antenna gains
match these values so accurate values are essential.
WTUV.......The weighting factor for data outside of the uv range given
full weight. <= 0 => 0.05.
Warning: SCMAP sets its own UVranges for self-cal and it is
a bad idea to have WTUV near zero when these ranges are
small.
WEIGHTIT...If > 0, change the data weights by a function of the
weights just before doing the solution. Choices are:
0 - no change weighting by 1/sigma**2
1 - sqrt (wt) weighting by 1/sigma may be more stable
2 - (wt)**0.25
3 - change all weights to 1.0
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 SN table to apply. 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
on input.
OUTFGVER...Flag table version to be used on output for both single-
and multi-source data sets. If OUTFGVER is <= 0 or
greater than FGmax (the previously highest FG version
number), then a new FG table will be created for the new
flags with version FGmax+1. This new table will also
contain the flags applied on input (if any) from FG
version FLAGVER. If OUTFGVER specifies a pre-existing FG
version, then the input flags are not copied even if
OUTFGVER and FLAGVER are not equal.
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.
<0 => no bandpass correction done.
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).
DOTV.......Display residuals on TV channel 1. > 0 => display field
number DOTV initially. Can be changed by TELL. When using
this option, you may interact with the residual images at
the end of each major cycle of Clean, selecting which field
is examined in what window, resetting the Clean boxes, and
stop the CLEANing of the current self-cal loop.
SCMAP additional option: DOTV < or > 0 => display field
number abs(DOTV) at the end of each Clean and interact with
that image including UV data editing options. If DOTV < 0,
the only display is at the end of each Clean else both are
done. DOTV = 0 => no TV display. It is strongly
recommended that you use at least DOTV = -1. That display
lets you change parameters including DOTV to resume the
display during Clean.
LTYPE......> 2 => label the TV image as
3 = Label with RA and DEC or other natural units
4 = Label in arcsec or other units from reference
pixel
5 = Label in arcsec or other units from subimage
center
6 = Label in pixels from original bottom left corner
Do just tick numbers and X and Y axis labels, leaving off
the time, source name, center coordinates, peak flux, and
other labels:
7 = Label with RA and DEC or other natural units
8 = Label in arcsec or other units from reference
pixel
9 = Label in arcsec or other units from subimage
center
10 = Label in pixels from original bottom left corner
Add n*100 to adjust metric scaling (see HELP LTYPE)
Sign not important here.
DOWEIGHT...The display of error bars in the editing phase depends on
the data weights being 1/(sigma**2) in 1 (Jy**2). Set
DOWEIGHT to get the data weights into this scale,
multiplying the input weights by DOWEIGHT. 0 -> 1.
DOTWO......> 0 (true) means to do the secondary plot of a second
observable (phase, amplitude, diff amplitude) from the
primary baseline in the editing phase. <= 0 means to plot
only the primary observable used for the editing. True is
highly recommended.
BADDISK....This array contains the numbers of disks on which it is
desired that scratch files not be located.
BADDISK has no effect on input and output data.
BPARM......Subarray relative weight factors; applied to all data.
CPARM......Subarray refence antenna (2->10 only).
EXPLAIN SECTION
SCMAP: Imaging - self-calibration loop task.
Documentor: W. D. Cotton, NRAO
Related Programs: CALIB, IMAGR, EDITR
This task will do multiple iterations of self-calibration and
imaging optionally starting with a one component model (SMODEL). Each
iteration consists of 1) a visibility-based imaging and Clean
deconvolution (like IMAGR), 2) determination of the appropriate number
of Clean components and self-calibration uvrange, and 3)
self-calibration of the visibility data based on the new model. A final
imaging/deconvolution is then done using the solution which gave the
best RMS/(sum CC) residual. This solution is then used to produce the
final output uvdata.
Only I polarization data is imaged but the resulting self-calibrated
uvdata will contain properly calibrated data for all input
polarizations.
For spectral line data a "continuum" data set should be formed from
selected line channels using SPLIT, UVCOP etc. and used as the input to
SCMAP. The resultant image can then be used with CALIB to calibrate the
line data set
This task uses a number of techniques to improve the efficiency and
stability of the self-calibration process. After the first Clean,
future Cleans may be restarted using some number of components from the
previous Clean. In addition, the minimum residual level is set the RMS
residual of the previous Clean.
The number of Clean components used in the next Clean is determined
from the value of APARM(8). The previous CC table is first merged and
then all components brighter than APARM(8) times the RMS residual of the
previous Clean are reused.
Depth of Clean:
Each self-calibration iteration SCMAP decides on the depth of the
Clean. The Clean proceeds until the absolute value of the residual is
the RMS residual of the previous iteration. This can be modified by
using adverbs NITER and FLUX. Cleaning never proceeds longer than NITER
iterations and FLUX will never be increased. Deeper Cleans can be
forced by setting FLUX to a small, but positive value and NITER to a
sufficiently large number. The final Clean is up to NITER components
with no minimum flux density level test.
The number of iteration is not a totally accurate determination of
the depth of Clean as the CC table is merged each cycle and some
components will be reused. Thus, the Clean is deeper than would be
obtained from the same number of components without merging.
Both NITER and FLUX may be adjusted interactively during the self-cal
TV interaction.
Uv Baseline Range:
The range of baseline lengths (UVRANGE) specified in the input is
only used in the imaging step. In each iteration of self-calibration
the appropriate uv range and number of Clean components to use is
determined heuristically. The Clean components are merged and all
components up to the first negative one are used. The corresponding uv
range for self-calibration is determined from comparison of the sum of
the flux in the Clean model and the distribution of average amplitudes
as a function of baseline length. Baselines longer that the longest
with an average higher that the summed Clean model are given full
weight. A slight tolerance (1 sigma) is used to allow for noise.
Baselines outside of the range given full weight are weighted by the
factor UVWT. Note there is no default and UVWT=0 causes this data to be
completely ignored.
Convergence:
The test for convergence is based on the RMS residual value (ignoring
the outer pixels) of the Clean image divided by the sum of the Clean
flux. Convergence is declared when either the convergence measure
increases by more than 10 percent or if more than three self-calibration
cycles has elapsed since the best solution. When convergence is
obtained the solution with the best convergence measure is used to
produce the final image and uv data.
Solution Mode:
The solution type can be set to either 'P', 'P!A', 'A&P' or ' '.
The first three will cause only solutions of the appropriate type to be
performed.
If SOLMODE is set to ' ' the self-calibration solutions are
initially done using only phase until the convergence measure no longer
shows improvment. The last self-calibration solution is then applied to
the input data and a new scratch file is filled with the result.
Further processing uses this data.
After the mode switch amplitude calibration is enabled and all
selected IFs and polarizations are averaged in the self-cal solutions.
The minimum number of antennas is changed to 4 if it is initially less
and gain constraint is enabled (APARM(2)). Also, the solution interval
(SOLINT) is doubled; or, if an initial value of 0 was given 30 seconds
is used.
Restarting:
If SCMAP previously terminated normally then the output uv data is
suitable for input for another execution. If SCMAP did not terminate
normally then the last SN table produced can be used as the starting
calibration (see DOCALIB and GAINUSE). This method can recover results
up to a switch between phase only and amplitude and phase calibration
(see discussion above on SOLMODE). After a mode switch the working data
is written to the output file. A restart can then use the output of the
previous run and the last SN table attached to it. If SCMAP terminated
normally there will be no SN tables attached to the output.
The output Clean image should always have a CC version 2 which is a
copy of the latest, merged CC table. This table can always be used with
CALIB to produce suitable input for SCMAP.
Limiting messages:
SCMAP can produce a large quantity of messages. These messages can
be limited using the verb MSGKILL. MSGKIL 4 will result in only the
most important messages.
****************************************************************
*********************** TV DISPLAYS ************************
****************************************************************
********************** During Clean: ***********************
The TV display may be used to follow the progress of your imaging
and Cleaning. If you set DOTV > 0, the dirty image of field DOTV will
be displayed before Clean begins and the residual image of the selected
field will be displayed after each major Clean cycle. When the image is
displayed, a menu of interactive options is also displayed. Move the TV
cursor to a desired option, and press TV button A, B, or C. To get help
on the message screen about an option, move the cursor to that option
and press TV button D. The selected option is highlighted in a
different color. If you select no options in 30 seconds, SCMAP will
continue without you until the end of the next major cycle. Interactive
options do not appear on the final display which is either of the dirty
image (NITER = 0) or the Clean image with components restored. If you
forget to turn on the TV display - or turn it off after starting SCMAP -
you may turn it back on with TELL SCMAP (say SHOW SCMAP in AIPS to see
all the TELL parameters that you may send to SCMAP after it has
started).
The interactive options appear in two columns. The left column
offers:
| ABORT TASK | Abort the task, ending things as rapidly as
possible.
| TURN OFF DOTV | Resume Cleaning now and turn off future TV
displays
| STOP CLEANING | Declare the Clean of this channel done, restore
components and write the output
| OFFZOOM | turn off any zoom magnification
| OFFTRAN | turn off any black & white enhancement
| OFFCOLOR | turn off any pseudo-coloring
| TVFIDDLE | as in AIPS, allows zoom, pseudo-color contours or
black and white enhancement
| TVTRAN | black and white enhancement as in AIPS
| TVPSEUDO | many pseudo-colorings as in AIPS
| TVFLAME | flame-like pseudo-colorings as in AIPS
| TVZOOM | interactive zoom magnification and center
| CURVALUE | display image intensity, pixel x/y at cursor
| IMSTAT | do robust and normal image statistics
| SET WINDOW | set sub-image display window
| RESET WINDOW | re-set display window to full image
When a field is displayed, the pixel increments are chosen to load the
full field to the TV screen. The TV window is even forced to be bigger
to show the image if needed and small fields are interpolated by up to a
factor of 3. The Clean boxes for the field are displayed in a graphics
overlay. You may select a smaller sub-image of the field for display in
greater detail, but SCMAP does insist that the sub-image includes all
Clean boxes for the field. You may use TVBOX or REBOX to create and
modify the Clean boxes interactively. Note that these set the number as
well as the type and parameters of the boxes. TVBOX deletes
pre-existing boxes and so, when there are same, it asks permission to
do so. If you do not answer Y or y it will do RENOX instead. This is
currently one of two interactive ways to set Clean boxes for fields
numbered > 1. The other if the verb FILEBOX in AIPS.
TVBOX: To set the number, type, and parameters of the Clean boxes for
the displayed field with a TV graphics display of the boxes as they are
being set. The terminal will issue instructions. While setting the
lower left corner of each box for the first time, buttons A and B will
mark the corner and switch to setting the upper right corner of the box.
Button C will change the rectangular box to a circular one and button D
will exit. Similarly, while first setting the center of a circular box,
buttons A and B switch to setting the radius, C switches back to a
rectangular box, and D exits deleting that incomplete box. While
setting or re-setting the upper right corner or radius of the box or
re-setting the lower left corner or center, button A marks the current
corner and switches to the other corner (or marks and switches between
radius and center), button B marks the current corner and switches to
the next (new) box, button C marks the current corner and switches to a
search mode leading to the resetting of a previous box, and button D
exits keeping the current and previous boxes with their current
settings. In search mode, move the cursor to any lower left or upper
right corner of any already set rectangular box or the center or any
point on the circumference of an already set circular box and press
button A or B to reset that corner or push button C to go on to the next
box. As usual button D exits. REBOX is TVBOX started with the current
boxes in a resetting mode.
The right-hand column offers the options:
| TVBOX | set number of Clean boxes and their parameters
interactively
| REBOX | modify and add Clean boxes for this field
| DELBOX | delete some of the current boxes
| CONTINUE CLEAN | Continue Cleaning now, not waiting for the timer
to expire
| CHAR MULT | To change character size (only if character scale
starts larger than 1)
If you turn off the TV display, you may restart it with TELL from AIPS.
****************************************************************
******************** Before self-cal: **********************
****************************************************************
The TV display may be used also (or instead) to follow the progress
of your imaging at the end of the Clean step before doing the next
self-cal. If you set DOTV not= 0, the residual image of field DOTV will
be displayed after Clean ends. When the image is displayed, a menu of
interactive options is also displayed. Move the TV cursor to a desired
option, and press TV button A, B, or C. To get help on the message
screen about an option, move the cursor to that option and press TV
button D. The selected option is highlighted in a different color. If
you select no options in 30 seconds, SCMAP will continue without you
until the end of the next major cycle of Clean (if selected) or until
the end of the next Clean. If you forget to turn on the TV display - or
turn it off after starting SCMAP - you may turn it back on with TELL
SCMAP (say SHOW SCMAP in AIPS to see all the TELL parameters that you
may send to SCMAP after it has started).
The interactive options appear in two columns. The left column
offers:
| ABORT TASK | Drive a silver stake through SCMAP's heart without
waiting for a full moon or even for midnight.
| TURN OFF TV | Resume processing now and turn off future TV
displays
| STOP SELFCAL | Declare the self-cal done, do a deeper Clean and
write out the final images and calibrated data set
| OFFZOOM | turn off any zoom magnification
| OFFTRANS | turn off any black & white enhancement
| OFFCOLOR | turn off any pseudo-coloring
| TVFIDDLE | as in AIPS, allows zoom, pseudo-color contours or
black and white enhancement
| TVTRAN | black and white enhancement as in AIPS
| TVPSEUDO | many pseudo-colorings as in AIPS
| TVFLAME | flame-like pseudo-colorings as in AIPS
| TVZOOM | interactive zoom magnification and center
| CURVALUE | display image intensity, pixel x/y at cursor
| SET WINDOW | set sub-image display window
| RESET WINDOW | re-set display window to full image
| SET PARAMETERS | Reset various adverb values.
| CHAR MULT | To change character size (only if character scale
starts larger than 1)
When a field is displayed, the pixel increments are chosen to load the
full field to the TV screen. The TV window is even forced to be bigger
to show the image if needed and small fields are interpolated by up to a
factor of 3. The Clean boxes for the field are displayed in a graphics
overlay. You may select a smaller sub-image of the field for display in
greater detail, but SCMAP does insist that the sub-image includes all
Clean boxes for the field. You may use TVBOX or REBOX to create and
modify the Clean boxes interactively. Note that these set the number as
well as the type and parameters of the boxes. TVBOX deletes
pre-existing boxes and so, when there are same, it asks permission to
do so. If you do not answer Y or y it will do RENOX instead. The
EDIT DATA selects a data editing tool described below. It is slow in
starting up so do not select this option more than needed.
SET PARAMETERS: Since SCMAP is run as an interactive task, TELLing it to
change parameters requires a second AIPS session and some care. This
option brings up a question and answer session that prompts you for all
TELL parameters plus a couple other useful ones. Answer with a blank
line (simple carriage return) to leave the parameter unchanged; answer
with a Q or q to stop the questioning. The parameters are, in order,
NMAPS, DOTV, SOLINT, APARM(10), NITER, APARM(9), APARM(8), FLUX, GAIN,
FACTOR, MINPATCH, MAXPIXEL, BMAJ, BMIN, BPA, REFANT, WTUV, SOLTYPE,
SOLMODE, SOLCON. If SOLMODE is already A&P due to a switch from P, do
not change it.
SWITCH TO A&P: If this option is offered, you may declare to SCMAP that
enough phase-only iterations have been done and that it is time to do
the switch to amplitude and phase. The option is offered only if
SOLMODE = ' ' to begin with and, then, only if the switch has not
already taken place. SCMAP applies the latest phase calibration to the
input data moving them to another file. Then it doubles the SOLINT and
does the remaining self-cals as A&P. If you want to ignore the previous
phase cals (other than by their effect on the current Clean image), use
SET PARAMETERS and change SOLMODE instead.
TVBOX: To set the number, type, and parameters of the Clean boxes for
the displayed field with a TV graphics display of the boxes as they are
being set. The terminal will issue instructions. While setting the
lower left corner of each box for the first time, buttons A and B will
mark the corner and switch to setting the upper right corner of the box.
Button C will change the rectangular box to a circular one and button D
will exit. Similarly, while first setting the center of a circular box,
buttons A and B switch to setting the radius, C switches back to a
rectangular box, and D exits deleting that incomplete box. While
setting or re-setting the upper right corner or radius of the box or
re-setting the lower left corner or center, button A marks the current
corner and switches to the other corner (or marks and switches between
radius and center), button B marks the current corner and switches to
the next (new) box, button C marks the current corner and switches to a
search mode leading to the resetting of a previous box, and button D
exits keeping the current and previous boxes with their current
settings. In search mode, move the cursor to any lower left or upper
right corner of any already set rectangular box or the center or any
point on the circumference of an already set circular box and press
button A or B to reset that corner or push button C to go on to the next
box. As usual button D exits. REBOX is TVBOX started with the current
boxes in a resetting mode.
The right-hand column offers the options:
| EDIT DATA | select the data editing tool to view visibility
data and current residuals and delete bad points
| TVBOX | set number of Clean boxes and their parameters
interactively
| REBOX | modify and add Clean boxes for this field
| SWITCH TO A&P | Switch from phase-only to amplitude and phase
| CONTINUE SELFCAL| Continue self-cal now, not waiting for the timer
to expire
If you turn off the TV display, you may restart it with TELL from AIPS.
That will require using a second AIPS session since the AIPS session
that started SCMAP is suspended until it ends.
****************************************************************
********************* While editing: ***********************
****************************************************************
SCMAP implements a version of task EDITR as a TV graphic editor
for uv data using the uv data themselves and the current residuals. It
works with the XAS-TV display graphics planes (7 of them) to allow you
to flag uv data based on their values. It does not change the input
data set, but will write a flag table used in the next step of self-cal.
The editor averages spectral channels and over a specified time
interval as it reads the data set(s). It attempts to read the entire
data set into the pseudo-AP memory when if starts up. If it cannot fit
all the data, it attempts to read just one IF at a time and/or all
baselines to one antenna at a time. In that case, when you switch IFs
or main antennas, the editor has to reads in the next IF or set of
baselines. The editor will tell you as it starts whether "All data will
reside in memory" or various other combinations. Judicious choices of
APARM(9) can help the task to read all selected data and thus to be more
efficient
There are 6 parts to the editor's display:
(1) A menu of operations displayed in two columns, one each at the left
and right sides of the screen. When the menu is displayed, move the
cursor to the desired item and press buttons A, B, or C. To get on-line
help in the message window about a given option, move the cursor to the
desired menu item and press button D.
(2) A plot at the bottom of the screen in a bright color (usually) of
the data which may be actively edited at present. It is of the chosen
type for the selected baseline, polarization, and IF and is limited in
time range by the current frame (which can be all or a portion of the
total time range). Flagged data are shown in a different color. The
time range of the frame may be made small to expand the time axis, but
may also be made so large as to cause serious crowding of the plotted
data points. (Increase your XAS window width to increase the plot
scale.)
(3) A plot above the edit area plot in the same bright color of the data
from the selected baseline, polarization, and IF. This plot is in a
second observable (e.g. if amplitude is in the edit plot, phase is often
the second observable). Data in this second area may not be used for
editing but should be helpful in choosing which data to delete in the
edit area. Flagged data are shown in a different color. This plot may
be suppressed by adverb DOTWO.
(4) 0-10 plots of data of the current data type, IF, and polarization
for a list of 0-10 other baselines to the main antenna are shown above
the second plot. They are shown for comparison using another color,
while flagged data are shown in a different color.
(5) Data from the Clean residuals will be shown in another color in each
of the windows (2, 3, 4) above. This display may be turned off and on
with a menu item.
(6) Several text areas also appear including (a) the start and end times
for the current frame's time axis, (b) the selected data type, IF, and
polarization at the bottom of the screen, (c) the antenna shown in each
plot at the top right of each plot, (d) the current all-IF,
all-polarization, and all-antenna flags, (e) the y-axis tick values on
each of the frame plots, and (f) while interactively setting time and/or
value ranges, the time and/or value to which you are currently pointing
and the associated source name.
You may change the size of the XAS window at any time. The editor
will not allow it to become too small, but will adjust its display for
all reasonable sizes.
The left-hand menu can contain
| FLAG TIME | To delete one time at a time.
| FLAG TIME RANGE | To delete one or more time ranges.
| FLAG BELOW | To delete all displayed times with data below a
cutoff value.
| FLAG ABOVE | To delete all displayed times with data above a
cutoff value.
| FLAG AREA | To delete one or more areas in the data-value -
time plane.
| FLAG POINT | To delete one sample at a time using both
horizontal and vertical cursor position.
| FLAG FAST | To delete samples using only mouse clicks
| ENTER AMPL RNG | To select the display range for amplitude plots.
Use 0 -1 for 0 to antenna maximum and
0 0 for min to max.
| ENTER PHASE RNG | To select the display range for phase plots.
| ENTER DAMP RNG | To select the display range for plots of the
amplitude of the visibility minus a running
vector average visibility.
| PLOT ERROR BARS | To plot error bars based on data weights
| SET SCAN LENGTH | To set the averaging time used to determine the
running average in seconds.
| LIST FLAGS | To list all flags now in the Flag Command table.
| UNDO FLAGS | To undo one of the flag operations in the FC table
| REDO FLAGS | To reapply all remaining flags after one or more
have been undone (see note below)
| SET REASON | To set the 24-character "reason" string to be put
in the uv-data flag table
| USE EXPERT MODE | To control the task from the keyboard instead of
the menu.
| HOLD TV LOAD | To stop updating the TV display with every change
of parameter; change several, then select
| DO TV LOAD | To update the TV display now and with each change
of display parameter.
| REPLOT | To do the current plot over again, recomputing
the differences from the running mean if
appropriate.
| EXIT | To exit editing, moving the FC table to a uv-data
FG table
| ABORT | To exit editing, deleting the FC table
The right-hand menu can contain
| NEXT CORRELATOR | To switch to viewing the next correlator,
switching to the other polarization and, if
needed, incrementing the IF.
| SWITCH POLARIZ | To switch to viewing and editing the other
polarization.
| SWITCH ALL POL | To switch functions from applying to one
polarization to applying to both polarizations
or vice versa.
| ENTER IF | To select which IF is viewed and edited. This
can force a read of data if all IFs did not fit
in memory.
| SWITCH ALL IF | To switch functions from applying to one IF to
applying to all IFs or vice versa.
| SWITCH ALL TIME | To switch FLAG ABOVE and FLAG BELOW between all
times and the time range of the frame
| ROTATE ALL ANT | To rotate functions from applying to (a) one
baseline, (b) all baselines to the main antenna,
and (c) all baselines.
| ENTER ANTENNA | To select the main antenna, baselines to which are
displayed on the screen.
| ENTER OTHER ANT | To select up to 11 other antennas to define the
baselines to be displayed; enter 10 numbers, 0's
are then ignored (to plot 5 enter the 5 plus 6
0's). The first one is used for the edit area.
| NEXT BASELINE | To rotate the list of other antennas, selecting
the next one for the edit area.
| NEXT ANTENNA | To select a new main antenna, one higher than the
current main antenna. The "others" MAY also
be adjusted.
| PLOT ALL TIMES | To display all data for the selected baselines.
| SELECT FRAME | To select a window into the current data
interactively.
| NEXT FRAME | To select the next time-range window of the same
size as the current frame.
| PREVIOUS FRAME | To select the previous time-range window of the
same size as the current frame.
| SHOW AMPLITUDE | To display and edit amplitudes.
| SHOW PHASE | To display and edit phases.
| SHOW DIFF AMPL | To display and edit the amplitudes of the vector
difference between the sample and its running
mean
| SHOW ALSO AMPL | To display amplitudes of the edit baseline for
reference with the phase or difference
amplitude edit window.
| SHOW ALSO PHASE | To display phases of the edit baseline for
reference with the amplitude or difference
amplitude edit window.
| SHOW ALSO DAMP | To display difference amplitudes of the edit
baseline for reference with the phase or
amplitude edit window.
| TV ZOOM | To alter the display zoom used while in the flag
functions.
| OFF ZOOM | To turn off any zooming.
| 2ND UV OFF | To disable the display of the residual uv data set.
| 2ND UV ON | To enable the display of the residual uv data set.
The menus will not show all of these options every time. The HOLD
TV LOAD option is shown until invoked, and then is replaced with the DO
TV LOAD. When that is invoked, the HOLD TV LOAD option reappears. The
SWITCH POLARIZ and SWITCH ALL POL options appear only if there are two
polarizations in the data. The ENTER IF option appears only if there is
more than one IF in the data and the SWITCH ALL IF option appears only
if there is more than one IF and all IFs fit in the program memory.
Only one of the three SHOW ALSO choices appears at any one time.
Plots of the difference between the visibility and its running mean
can be particularly sensitive to short term disturbances while ignoring
slow changes due to gradually changing source structure and the like.
The running mean is not carried between sources and, as a result, is not
normally carried across scan boundaries.
Note that value-dependent flagging (FLAG BELOW, ABOVE, AREA) use
the values currently plotted to make a list of value-independent flag
commands (i.e., a single time for the specified antennas, IFs,
polarizations, etc.). When a value-dependent FLAG operation is undone
(UNDO FLAGS) or redone (REDO FLAGS), it is these value-independent flags
which are undone or redone. You may have to undo more commands and then
repeat FLAG commands to get the results you could have gotten by doing
the now desired value-dependent command in the first place. You need
also to be careful with the ROTATE ALL ANT setting with these
value-dependent commands. If one baseline is set, then the commands
only apply to the current baseline. If one antenna is set, the commands
apply to all baselines to the current main antenna, while if all
antennas is set, the commands apply to all baselines. The first two set
a clip level, below or above which data are deleted, based on the value
of the observable in each baseline independently. The FLAG AREA
command, however, only looks at the values of the observable in the main
edit baseline and flags those samples from all applicable baselines.
Be careful when choosing EXIT versus ABORT. The former applies the
flag commands to a flag table attached to the input uv data, the latter
causes the flag commands to disappear without a trace.
The colors used by EDITR are those of the various graphics planes
when it begins to run. You may change them with the AIPS verb GWRITE to
more desirable colors. The planes are:
Plane Default RGB Use
1 1.00 1.00 0.00 Main editing and secondary windows
2 0.06 1.00 0.00 Comparison baseline data windows
3 1.00 0.67 1.00 Menu highlight
4 0.00 1.00 1.00 Edit and frame window boundaries
5 1.00 0.18 0.18 Flagged data in all windows
6 0.60 0.60 1.00 Menu foreground
7 1.00 0.80 0.40 Second uv data set if present
You may wish to change the colors to ones that you can see better.
In "expert" mode, you are prompted with a set of 4-character codes.
You type in the letter within that code that is shown in upper case
(left-justified with a carriage return) to get the desired function.
The expert functions allowed are
Code Prompt Full menu OP name
T Time FLAG TIME
R Rang FLAG TIME RANGE
B Belo FLAG BELOW
A Abov FLAG ABOVE
E arEa FLAG AREA
O pOin FLAG POINT
Q Quik FLAG FAST
L List LIST FLAGS
U Undo UNDO FLAGS
S baSl NEXT BASELINE
C nCor NEXT CORRELATOR
N Nant NEXT ANTENNA
F Fram SELECT FRAME
M aMpl SHOW AMPLITUDE
P Phas SHOW PHASE
D aDif SHOW DIFF AMPL
X eXit EXIT EXPERT MODE
H Help THIS HELP LIST
although some may be suppressed depending on what is currently
displayed.