; RSTOR
;---------------------------------------------------------------
;! Restores a Clean component file to a map with a Gaussian beam.
;# Task Imaging AP
;-----------------------------------------------------------------------
;;  Copyright (C) 1995, 2005, 2018-2019
;;  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.

        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.
----------------------------------------------------------------
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.

