AIPS HELP file for RSTOR in 31DEC24
As of Fri Apr 26 16:48:21 2024
RSTOR: Restores a CC file to an image with a gaussian beam.
INPUTS
Input image
INNAME Image name (name)
INCLASS Image name (class)
INSEQ 0.0 9999.0 Image name (seq. #)
INDISK 0.0 9.0 Image disk drive #
BLC 0.0 Used to specify plane.
Image with CC file appended
IN2NAME Image name (name)
IN2CLASS Image name (class)
IN2SEQ 0.0 9999.0 Image name (seq. #)
IN2DISK 0.0 9.0 Image disk drive #
INVERS 0.0 46655.0 CC file ver. no.
Output image
OUTNAME Image name (name)
OUTCLASS Image name (class)
OUTSEQ -1.0 9999.0 Image name (seq. #)
OUTDISK 0.0 9.0 Image disk drive #
NITER 0.0 Number of CLEAN components to
restore.
BMAJ * -999.9 FWHM(asec) maj. axis CLEAN
restoring beam.
BMIN * -999.9 FWHM(asec) min. axis CLEAN
restoring beam.
BPA * -360.0 360.0 CLEAN beam position angle
FACTOR Scale CCs by FACTOR
BADDISK -1.0 1000.0 Disks to avoid for scratch.
HELP SECTION
RSTOR
Type: Task
Use: RSTOR does an AP-based restoration of a CC file to a map. It is
basically a gutted version of APCLN. The CC file is copied from
the second input map (which may be the same as the first input
map) to the output.
A single plane in a cube may be processed per run; the
resulting restored image will be put in the corresponding plane
of the output image. Other planes in the output image will not
be affected, i.e. will contain garbage on the initial run. For
cubes, the CC file on the output map will have a version number
equal to the plane number (i.e. BLC(3)). When several runs of
RSTOR are made to restore a cube be sure to completely specify
the output image, and also correctly specify the input CC file.
To remove Clean Components convolved with a particular Clean
beam and then restore with another: First use RSTOR with the
first and second images the same, BMAJ=BMIN=0, FACTOR=-1. Then
run RSTOR with the first image the output of the first step, the
second image unchanged, FACTOR=1, and BMAJ/BMIN/BPA whatever you
wish for the new beam.
Adverbs:
INNAME......The input map image name. Standard defaults.
INCLASS.....The input map image class. Standard defaults.
INSEQ.......The input map image sequence number. 0 => high
INDISK......The input map image disk drive no. 0 => any
BLC.........The third and higher dimensions are used to specify the
plane in the input and output images to be processed.
NOTE: process in increasing plane number.
IN2NAME.....The image name for the CC file. blank => actual INNAME,
otherwise standard defaults.
IN2CLASS....The CC image class. Blank => actual INCLASS.
IN2SEQ......The CC image sequence number. 0 => actual INSEQ
IN2DISK.....The CC image disk drive no. 0 => any
INVERS......The CC file version number. 0=> highest current one.
OUTNAME.....The restored map image name. blank => actual
INNAME.
OUTCLASS....The output map image class. Standard behavior with
default = 'QRST' if INCLASS = 'Q...'
'URST' if INCLASS = 'U...'
'VRST' if INCLASS = 'V...'
'RRST' if INCLASS = 'R...'
'LRST' if INCLASS = 'L...'
'IRST' if INCLASS = anything else
OUTSEQ......The restored map image seq. no., 0=> highest unique
If >0: image will be created if new, overwritten if
image name exists and is a cube. RSTOR will not
overwrite existing single-plane images.
OUTDISK.....Restored Map disk drive no., 0=> highest with space
NITER.......Number of CLEAN components to restore. 0 => all.
Also, if NITER > actual number of components, all
will be restored.
BMAJ........The FWHM (asec) major axis of the restoring beam.
If 0: value obtained from input image; RSTOR will
die if there is no beam in the input header.
If -1: Clean components will be restored as
delta-functions.
BMIN........The FWHM (asec) minor axis of the restoring beam.
BPA.........The position angle in the unrotated image of BMAJ.
FACTOR......Add the Clean components scaled by FACTOR. Thus a
FACTOR=-1 will subtract the CCs, presumably from an
image that already had them restored.
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.
EXPLAIN SECTION
RSTOR: Restores a CC file to an image with a gaussian beam.
DOCUMENTOR: Patrick Leahy (NRAO/VLA)
RELATED PROGRAMS: UVMAP,APCLN,IMAGR,CALIB,UVSUB,CCMOD,PRTCC,
VTESS,UTESS,LTESS,IMMOD
PURPOSE
RSTOR is in effect simply the last stage of APCLN. See the
help file for the latter for comments on CLEANing and the
rationale for using a restoring beam at all. The main reason
for having RSTOR as a seperate program is to facilitate the
combination of CLEAN with other image restoration algorithms,
and in particular the Maximum Entropy Method, implemented in
AIPS as the task VTESS. Combining CLEAN and MEM is a useful
strategy when your image contains both bright compact structure
and faint diffuse structure because each algorithm works well
for one and poorly for the other. In this case it is useful
to CLEAN the image until the peak residual is close to the
surface brightness of the more extended structure. If APCLN or
IMAGR are run with BMAJ = -1, they will then output the residual
map. This can then be processed by VTESS (or a similar program).
If you use IMAGR, remember that VTESS, like APCLN, needs an image
twice as large as the final processed region. Finally, the
clean components, convolved with the appropriate beam, can be
added back to the convolved MEM map with RSTOR.
RSTOR can also be used to restore clean components to a
clean residual map, as a (slightly faster) alternative to
restarting CLEAN. Note that RSTOR always creates a new output
map (except when processing cubes) and does not overwrite the
residual map (unlike APCLN and IMAGR). It also does not use the
dirty map and beam.
COMMENTS
DON'T USE RSTOR:
If only one or a few point sources need restoring. It is
quicker to use IMMOD. (Also, in this case it's quicker and more
accurate to do the subtraction "by hand", using IMFIT to locate
the points on the dirty image (or a preliminary CLEAN image) and
UVSUB to do the subtraction via the SMODEL option.
NITER
Usually you should restore all the clean components, which
is the default if NITER is 0. However you can create a "DIY"
residual map via UVSUB and UVMAP, and in this case you may not
have subtracted all the original clean components.
BMAJ, BMIN, BPA
The restored map may be easier to interpret if BMIN is set
equal to BMAJ, so that the restoring beam is a circular
Gaussian, and any elongated structures are therefore seen in
their correct orientation. The frailties of CLEAN's
deconvolution will be least apparent if both are set equal to
the LONGEST dimension of the dirty beam.
Attempts to "super resolve" the source by setting BMAJ and
BMIN to the SHORTEST dimension of the dirty beam (or shorter)
skate on the proverbial thin ice, the more so if the number of
clean components is comparable to, or larger than, the
number of independent visibility data used to make the dirty
map.
Note that if BMAJ, BMIN and BPA differ greatly from those
of the main lobe of the dirty beam, the parts of the Clean Map
derived from the clean components and the residual map will have
greatly different resolutions. This is very dangerous if the
residuals contain significant emission. In this case your best
bet to get the scaling of the residual and restored flux equal
is to make sure the area of the fitted beam is close to the area
of the restoring beam, e.g. by setting BMAJ and BMIN to the
geometric mean of the dimensions of the dirty beam. But remember
that the effective area of the dirty beam changes with the size
of object being convolved (and on the size of the window over
which you integrate); ideally all significant flux density
should have been cleaned (or VTESSed) out of the residual map.
If you are restoring to a VTESS convolved output file
(extension IVTC), you should use the same restoring beam as
VTESS. This will be picked up from the input header if BMAJ =
0.
If BMAJ is set to -1, no convolution is done. This is
useful (for instance) in restoring clean components to a VTESS
map (the unconvolved version, extension .IVT) produced by
VTESSing a CLEAN residual map. The resulting map can be
subtracted from or divided into the data with UVSUB, for use in
error checking or as a step towards self-calibration. Naturally the
detailed structure of such maps is not to be taken literally!
Considerations for RESTORing Cubes
Spectral line cubes and other multidimensional images may
be restored one plane per run of RSTOR. The adverb BLC is
used to specify the desired plane. The output file will be the
same size as the input file and only the specified plane in the
output file will be modified. Thus, other planes will contain
garbage until they are processed. A separate components file
will be created for each plane (up to 46655) with sequence
number equal to the (1-rel) plane number.
NOTE: the planes should be processed in increasing plane
number in order to insure that the corresponding CLEAN
components file has the correct version number. If this gets
messed up, a restart using previous CLEAN components will pick
up the wrong components list.