AIPS HELP file for WFCLN in 31DEC09
As of Sun Nov 22 0:00:51 2009
WFCLN: Wide field imaging/CLEAN task - use IMAGR instead
INPUTS
INNAME Input UV data (name)
INCLASS Input UV data (class)
INSEQ Input UV data (seq. #)
INDISK Input UV data disk drive #
IN2NAME UV work file name
IN2CLASS UV work file class
IN2SEQ 0.0 0.0 UV work file seq - MUST BE 0
IN2DISK UV work file disk
BCHAN 0.0 8192.0 Low freq. channel 0 for cont.
ECHAN 0.0 8192.0 Highest freq channel
CHANNEL Restart channel number
NCHAV Number of chan. to average.
CHINC Channel incr. between maps.
STOKES Stokes parameters (see HELP)
BIF First IF in average.
EIF Last IF in average.
OUTNAME Output image name (name)
OUTDISK Output image disk drive #
OUTSEQ -1.0 9999.0 Output seq. no.
OUTVER CC ver. no (Continuum only)
CELLSIZE 1.E-12 (X,Y) size of grid in asec
IMSIZE 0.0 4096. Minimum image size
NFIELD 0. 4096. Number of fields (max 4096)
FLDSIZE 0. 4096. Size of each field.
RASHIFT RA shift per field (asec)
DECSHIFT DEC shift per field (asec)
NBOXES 0.0 50.0 Number of boxes for CLEAN
NB: field 1 only.
CLBOX -2.0 4096.0 Four coordinates for each box
UVTAPER 0. (U,V) Gaussian taper
units are kilo-lambda
UVRANGE 0. Min & max baseline (klambda)
UVWTFN UV dist. weight function
blank => uniform
UVBOX 0. 128. Additional rows and columns
used in weighting.
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
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
BCOMP Begin at BCOMP component
Specify for each field.
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
PHAT 0.0 999.0 Prussian hat height.
FACTOR -5.0 5.0 Speedup factor see HELP
CMETHOD Modeling method:
'DFT','GRID',' '
CPARM Task enrichment parameters
(1) Antenna diameter (m)
(2) Source Spectral index
(3) Frequency scaling factor
(4) >0 => do DFT imaging
(5) >0 => scale residuals
(6) Halfwidth in x of beam
(7) Halfwidth in y of beam
GUARD -1.0 0.9 x,y guard band fractional
radius
MAXPIXEL 0.0 500000.0 Maximum pixels searched in
each major cycle.
BADDISK -1.0 1000.0 Disks to avoid for scratch.
BOXFILE Input file for clean boxes
' ' => use NBOXES, CLBOX
HELP SECTION
WFCLN
Type: Task
Use: Wide field imaging/CLEANing task. WFCLN has been replaced by
IMAGR for all uses.
WFCLN does a visibility base CLEAN similar to MX but
offers a variety of corrections related to imaging wide
fields and/or multi or wideband frequency observations.
These are:
1) Relative frequency dependent primary beam
corrections in the CLEAN subtractions from the visibility
data.
2) Simple correction for source spectral index.
3) Correct errors in assumed center frequency.
4) Uses double size beam if possible for CLEANs.
5) Labels images with average zenith and parallactic
angles so that snapshot VLA images can be corrected with
OHGEO for misaligned coplanar array geometric distortion.
6) Supports 3-D DFT imaging to avoid noncoplanar array
image distortion. (THIS IS REALLY SLOW!)
7) After CLEANing the residuals may be scaled by the
ratio of the restoring beam area to the dirty beam area.
CPARM(5) > 0 enables this option. The dirty beam area is
determined in a box centered on the peak of half width
CPARM(6) in x (RA) and CPARM(7) in y (dec).
Adverbs:
INNAME.....Input UV data file (name). Standard defaults.
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.
IN2NAME....UV data work file name. This file is used as the
scratch file and may be used when restarting WFCLN
or to examine the final residuals. Default=OUTNAME.
RESTARTING WITH A PRE-EXISTING FILE APPEARS NEVER
TO BE QUICK IN WFCLN AND IS REPORTED TO CAUSE THE
TASK TO FAIL SOMETIMES. THEREFORE, YOU WILL ALWAYS
BE GIVEN A NEW WORK FILE.
IN2CLASS...UV work file class. Default='WFCLN'
IN2SEQ.....UV work data file sequence number.
<= 0 => highest existing + 1.
IN2SEQ IS FORCED TO BE 0 TO CREATE A NEW WORK FILE
EVERY TIME. (See above)
IN2DISK....UV work data file disk number.
BCHAN......First channel number to image, 0=>1.
Channel numbers are 1 relative as defined in the
input data file.
ECHAN......Highest channel number to to include in image,
0=>MAX The actual # of output channels will be
(BCHAN-ECHAN+1-NCHAV)/CHINC + 1
Thus, ECHAN is the highest channel in the input
averaged into the output.
There is a limit of 46655 channels.
CHANNEL....To restart a map/CLEAN with a given frequency
channel, specify that (input) channel in CHANNEL
NCHAV......NCHAV is the number of channels to be averaged
together in in the gridding process. 0 => 1.
If this value is less than the total number of
channels, then a multi-channel image will result.
CHINC......Number of input channels to skip between images.
0 => 1
STOKES.....Make images with this STOKES parameter. Unlike
UVMAP only one STOKES is permitted per execution.
(A beam is made for each frequency channel)
'I', 'Q','U', 'V', 'R' (=RCP), 'L' (=LCP)
BIF........The lowest numbered IF to include. Multiple IFs
can be included in a bandwidth synthesis average.
0 => 1.
EIF........The highest numbered IF to include. 0 =>highest.
Note: not all data sets will have IFs.
OUTNAME....Output image name (name). Standard defaults.
OUTDISK....The disk drive # of output images. 0 => highest with
space (note: map and Beam go on same disk. Note:
OUTCLASS='xCLnnn' where x=Stokes, nnn=field number and
'xBM001' is the beam CLASS. If NITER=0,
OUTCLASS='xIMnnn'
OUTSEQ.....Output sequence number.
Note: All maps and beam have same sequence number.
0 => highest to produce unique maps and beam.
OUTVER.....CC table version number for continuum data only.
For line data the channel number is used for the
version number.
CELLSIZE...(X,Y) pixel separation in asec.
IMSIZE.....(X,Y) The minimum desired size of the fields, regardless
of the FLDSIZE for component search.
NFIELD.....The number of fields to map in the antenna beam.
Up to 4096 are allowed but should be non overlapping.
FLDSIZE....(X,Y) field size in pixels for the component search
during cleaning; one per field. Should be in the range
32X32 to 4096X4096. Output image size will be increased
to the next highest power of two, but only the region
specified will be searched for components. Default is
IMSIZE-10
RASHIFT....RA shift of the phase center of each field from the tangent
point of the uv data in asec. Map center = tangent point +
shift. If X>0 shifts map center to east. NOTE: RASHIFT is
a shift in RA scaled by cos (Dec_0) as
Ra_new = RA_0 + RASHIFT/cos (Dec_0)
where _0 => the tangent point in the uv data. If the UV
data have been rotated then RASHIFT and DECSHIFT refer to X
and Y in the new coordinate system.
The DO3DIMAG option in IMAGR is not supported by WFCLN.
DECSHIFT...Declination shift of map center from tangent point of each
field in asec. Map center = tangent point + shift. If Y>0
shifts map center to north.
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 BLC and TRC 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.
UVTAPER....(U,V) Gaussian taper (kilo-lambda) at 30 percent level
UVRANGE....(Minimum,Maximum) baseline (kilo-lambda) in map.
UVWTFN.....Weighting function of (u-v) place.
blank=>Uniform; 'NA'=>Natural
'O '=> Set weights to One and do uniform weighting.
'V '=>VLBI weighting, forth root of input weight,
and do uniform weighting.
'NO'=>Set weights to one and use natural weighting.
'NV'=>VLBI weight and use natural weighting.
Note: uniform weighting in WFCLN corrects by the
sum of the weights in the box rather than the
number of visibilities as in MX.
UVBOX......(U,V) box size for smoothing. See HELP UVBOX.
ZEROSP.....(1)= zero spacing flux density for the
polarization being processed. Zero spacing flux is
placed at the center of FIELD 1.
(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.
ZEROSP(5) is 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.
GAIN......The CLEAN loop gain. 0 => 0.10.
FLUX......Stop CLEAN when abs(resid. image max) < FLUX (Jy)
IF FLUX < 0 then Clean stops at first negative
Clean Component.
MINPATCH..Minimum half width of the portion of the beam
which is used in the AP minor CLEAN. (init 51)
Use 51 for deep CLEANs of extended sources. Use
a large value if the beam has big side-lobes.
NITER.....CLEAN iteration limit. 0 => no CLEANing.
BCOMP.....Restart CLEAN using BCOMP(i) components for each
field i. If >0, you must completely specify the
OUTNAME and OUTSEQ of the clean map(s).
BMAJ......The FWHM (asec) major axis of the restoring beam.
If 0; value obtained from fitting to the beam.
If <0; output will contain the residual image.
BMIN......The FWHM (asec) minor axis of the restoring beam.
BPA.......The position angle in the unrotated image of BMAJ.
PHAT......The offset added to the pixel at the beam peak.
Should be about /2* but
you may well need to experiment.
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.
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.
CPARM.....Correction control parameters (SEE EXPLAIN WFCLN):
(1) If > 0 then make frequency dependent primary
beam corrections assuming an antenna diameter of
CPARM(1) meters.
(2) Visibility amplitudes will be corrected to the
average frequency assuming a spectral index of
CPARM(2). Note: the typical optically thin
synchrotron spectral index is about -0.7.
(3) If this value is larger than 0 then the u,v and
w terms are scaled by CPARM(3) before imaging.
(4) If this value is larger than 0 then use a DFT
onto the celestial sphere. THIS IS VERY SLOW.
(5-7) If (5) > 0 then scaling od residuals is
requested and
CPARM(6) = Halfwidth in x of box to determine the
dirty beam area (default = 5)
CPARM(7) = Halfwidth in y of box to determine the
dirty beam area (default = 5)
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).
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.
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 maps.
BOXFILE...Input file of clean box definitions . This is a text
file containing the coordinates of clean boxes for
all fields. The format is one box per line, as
follows:
field blc-x blc-y trc-x trc-y (5 integers)
e.g.
1 200 205 220 222
1 230 232 240 241
2 100 100 130 121
...
Fields with no boxes specified default to the size
specified by IMSIZE and FLDSIZ (see above). Use of
this input overrides all other clean box information.
E.g. BOXFILE 'FITS:BOXES'
If BOXFILE = ' ', NBOXES and CLBOX apply.
EXPLAIN SECTION
WFCLN: Widefield or wideband imaging/CLEANing task.
Documentor: W. D. Cotton, NRAO
Related Programs: MX, OHGEO, UBAVG
This task does a visibility based CLEAN similar to MX but
contains a number of optional corrections and enhancements which
are useful for imaging a wide field of view and/or using
multiple or wide frequency bands.
Frequency Dependent Primary beam corrections:
If multiple, widely spaced frequencies are used in a making
a single image then the differences in the primary beam size can
vary signifigantly with frequency. This causes problem in
CLEANing objects far from the pointing center as the primary
beam differences cause the subtraction of the combined model
from the visibility data at the different frequencies to be
incorrect. There will be residuals in the visibility data that
cannot be CLEANed as the data does not correspond to a possible
sky brightness distribution.
If CPARM(1) is larger than 0 then a correction is made in the
subtraction to remove the effects of the frequency dependence of
the primary beam. The primary beam is assumed to be a uniformly
illuminated disk of diameter CPARM(1) meters. This correction
is made out to the 5 percent power point of the beam with a flat
correction further out.
Note: this correction is only for the relative primary beam
to correct to a common frequency and DOES NOT correct for the
primary beam pattern at this frequency.
Simple Correction for Spectral Index:
If the sources observed do not have a flat spectrum then the
source spectrum will have effects on the CLEANing of a similar
nature to the frequency dependent primary beam problem described
above. This problem does not depend on position in the field
except in the the spectral index can vary across the field.
In general the spectral index does vary in an image but in many
cases the spectral index is usually closer to -.7 than to 0. To
the degree that the structure in the field can be characterized
by a single spectral index the amplitudes of the data can be
scaled to the average frequency.
Before imaging the amplitudes of the uv data are scaled to
the average frequency using a spectral index of CPARM(2). For
optically thin synchrotron sources this spectral index is
typically between -0.6 and -1.0. This correction cannot remove
the effects of variable spectral index but allows a single
correction.
Error in the Assumed Central Frequency:
If the frequency used to compute the u, v a, w terms is in
error then there will be a misscaling of the image due to this
error. Central frequencies are frequently computed on the basis
of unrealistic models of the bandpass shape.
If CPARM(3) is larger than 0 it is assumed to be a frequency
scaling factor for the u, v, and w that is to be applied before
imaging.
Array Misorientation Effects
Images made with a coplanar array not oriented towards the
instrumental zenith will have a distortion of the geometry which
increases in severity away from the phase tracking center. For
noncoplanar arrays the image is distorted rather than just the
geometry. VLA snapshots are misaligned coplanar arrays whereas
VLA synthesis images cannot be considered to be made with a
coplanar array.
Images made with misaligned coplanar arrays can be corrected
using task OHGEO to remove the effects of this misalignment.
This correction requires the knowledge of the observing
geometry; in particular, the average parallactic and zenith
angles. WFCLN computes these values and leaves then as header
keywords where OHGEO can use them.
Noncoplanar Effects
If the observing array is not confined to a plane during the
observations then images produced from a 2-D FFT will be
increasing distorted from the phase center. If this is a
serious problem then using a direct Fourier transform (DFT) to
image onto the celestial sphere can eliminate this problem.
However, THIS IS VERY SSSLLLOOOWWW. In addition, the dirty beam
is no longer a stationary function of position in the field and
a very conservative visibility based CLEAN is needed making this
EVEN SLOWER.
If CPARM(4) is greater than 0 then imaging and model
subtraction will be done using a DFT. Be prepared to wait.
There is also a limit of 1 field in this mode. There are
several other changes in the cleaning for this mode; especially,
the beam patch used is fixed at a small value.
Since the speed of the DFT imaging is directly proportional
to the number of visibilities time averaging is advised. Task
UBAVG can be used to time average to the maximum possible extent
without distorting a specified field of view.
Scaling residuals
In general the units of the residuals are different than
those of the restored components; either being Jy per beam area.
If the dirty beam area is similar to the restoring beam area
then this effect is negliglible. Similarly, if the CLEAN has
proceeded well into the noise then this difference is of little
consequence. However, if there is signifigant unCLEANed flux
left in the image then this difference may be important.
If CPARM(5) > 0 then WFCLN will attempt to scale the
residuals to the same units as the restored components. The
principle difficulty is determining the effective area of the
dirty beam. Operationally this is done inside a box centered on
the peak in the beam with halfwidth CPARM(6) in x and CPARM(7)
in y.