; RSTOR ;--------------------------------------------------------------- ;! Restores a CC file to a map with a gaussian beam. ;# Task Imaging AP ;----------------------------------------------------------------------- ;; Copyright (C) 1995, 2005 ;; Associated Universities, Inc. Washington DC, USA. ;; ;; This program is free software; you can redistribute it and/or ;; modify it under the terms of the GNU General Public License as ;; published by the Free Software Foundation; either version 2 of ;; the License, or (at your option) any later version. ;; ;; This program is distributed in the hope that it will be useful, ;; but WITHOUT ANY WARRANTY; without even the implied warranty of ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the ;; GNU General Public License for more details. ;; ;; You should have received a copy of the GNU General Public ;; License along with this program; if not, write to the Free ;; Software Foundation, Inc., 675 Massachusetts Ave, Cambridge, ;; MA 02139, USA. ;; ;; Correspondence concerning AIPS should be addressed as follows: ;; Internet email: aipsmail@nrao.edu. ;; Postal address: AIPS Project Office ;; National Radio Astronomy Observatory ;; 520 Edgemont Road ;; Charlottesville, VA 22903-2475 USA ;----------------------------------------------------------------------- RSTOR LLLLLLLLLLLLUUUUUUUUUUUU CCCCCCCCCCCCCCCCCCCCCCCCCCCCC RSTOR: Restores a CC file to an image with a gaussian beam. 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. ---------------------------------------------------------------- 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. RSTOR does not support TELL or TV options. 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. ---------------------------------------------------------------- RSTOR: Restores a CC file to an image with a gaussian beam. DOCUMENTOR: Patrick Leahy (NRAO/VLA) RELATED PROGRAMS: UVMAP,APCLN,MX,ASCAL,UVSUB,CCMOD,PRTCC,VBCC, 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 MX 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 MX, 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 MX). 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 (using the BPARM(1) = -1 option in ASCAL). 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.