; APCLN ;--------------------------------------------------------------- ;! Deconvolves images with CLEAN algorithm ;# Task Imaging AP ;----------------------------------------------------------------------- ;; Copyright (C) 1995, 1999 ;; 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 ;----------------------------------------------------------------------- ;--------------------------------------------------------------- APCLN LLLLLLLLLLLLUUUUUUUUUUUU CCCCCCCCCCCCCCCCCCCCCCCCCCCCC APCLN: Task which cleans an image using the BGC-AP algorithm Dirty 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. Beam image IN2NAME Image name (name) IN2CLASS Image name (class) IN2SEQ 0.0 9999.0 Image name (seq. #) IN2DISK 0.0 9.0 Image disk drive # Clean 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 # INVERS -1.0 46655.0 CC file ver. no. GAIN * 0.0 2.0 CLEAN loop gain FLUX * 0.0 Min. residual in window (Jy) PHAT 0.0 100.0 Prussian hat size. NITER * Maximum # of CLEAN components BITER Begin at BITER component 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 NBOXES 0.0 50.0 Number of boxes for CLEAN CLBOX 0.0 8192.0 Four coordinates for each box FACTOR * -5.0 5.0 Speedup factor see HELP APCLN MINPATCH * 0.0 1024.0 Min. BEAM halfwidth in AP. MAXPIXEL * 0.0 500000.0 Maximum pixels searched in each major cycle. DOTV * -1.0 1.0 TV display of residuals? BADDISK -1.0 1000.0 Disks to avoid for scratch. ---------------------------------------------------------------- APCLN Type: Task ******** IMAGR is strongly recommended over UVMAP/APCLN ****** Use: APCLN does an AP-based CLEAN of the type devised by B.G.Clark. CLEAN components are found by CLEANing the brightest points in the residual map with a small area of the dirty beam. More exact CLEANing is then done by transforming the CLEAN components, multiplying by the transform of the dirty beam, then transforming back to the map plane and subtracting the result from the dirty map. APCLN may be restarted if further CLEANing is desired. The dirty beam may be modified by adding a delta function of amplitude PHAT centered on its peak. TJC claims that this encourages smoothness in the clean map. A single plane in a cube may be processed per run; the resulting CLEAN (or residual) image will be put in the corresponding plane of the output image. Other planes in the output image will not be affected, i.e. are likely to contain garbage. When several runs of APCLN are made to CLEAN a cube be sure to completely specify the output image. A clean components table will be created with a sequence number corresponding to the plane number. APCLN now partially supports assymmetric beams, see the EXPLAIN section for more details. APCLN supports TELL including some change of parameters: see SHOW APCLN. Adverbs: INNAME......The dirty map image name. Standard defaults. INCLASS.....The dirty map image class. Standard defaults. INSEQ.......The dirty map image sequence number. 0 => high INDISK......The dirty map image disk drive no. 0 => any BLC.........The third and higher dimensions are used to specify the plane in the dirty and residual images to be processed. NOTE: process in increasing plane number. IN2NAME.....The dirty beam image name. blank => actual INNAME, otherwise standard defaults. IN2CLASS....The dirty beam image class. Standard defaults except blank => 'RBM001' if INCLASS = 'RIM001' 'LBM001' if INCLASS = 'LIM001' 'IBM001' if INCLASS = anything else IN2SEQ......The dirty beam image sequence number. 0 => actual INSEQ IN2DISK.....The dirty beam image disk drive no. 0 => any OUTNAME.....The clean map image name. blank => Standard defaults based on INNAME. OUTCLASS....The clean map image class. Standard behavior with default = 'QCL001' if INCLASS = 'QIM001' 'UCL001' if INCLASS = 'UIM001' 'VCL001' if INCLASS = 'VIM001' 'RCL001' if INCLASS = 'RIM001' 'LCL001' if INCLASS = 'LIM001' 'ICL001' if INCLASS = anything else OUTSEQ......The clean map image seq. no., 0=> highest unique If >0; image will be created if new, overwritten if image name exists. OUTDISK.....Clean Map disk drive no., 0=> highest with space INVERS......The CC file version number. 0=> highest current one. -1 => create new one. If none exist, one will be created in any case. GAIN........The CLEAN loop gain. 0 => 0.10 Can be reset with TELL. FLUX........Stop CLEAN when abs(resid. image max in CLEAN window) < FLUX (Jy). Can be reset with TELL. PHAT........The offset added to the pixel at the beam peak. Should be about 0.1 to 0.5 NITER.......CLEAN iteration limit. 0 => 200 If <0 then the CLEAN will stop at the first negative component or ABS (NITER) whichever is encountered first. Can be reset with TELL. BITER.......Begin new CLEAN at iteration BITER. If >0, you must completely specify the OUTNAME, OUTCLASS and OUTSEQ of the clean map. BMAJ........The FWHM (asec) major axis of the restoring beam. If 0; value obtained from dirty image. If <0; output will contain the residual image. Can be reset with TELL. BMIN........The FWHM (asec) minor axis of the restoring beam. Can be reset with TELL. BPA.........The position angle in the unrotated image of BMAJ. Can be reset with TELL. NBOXES......Number (<=50) of rectangular search boxes. 0 => 1 CLBOX.......A 4x50 array with the BLC and TRC of each box. 0 => use inner quarter of input map (first box) 0 => ignore box (boxes 2 - 50) 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 reset with TELL. MINPATCH....Minimum half width of the portion of the beam which is used in the AP minor CLEAN. < 3 => 127. Use 51 for deep CLEANs of extended sources. Can be reset with TELL. Upper limit 1024. MAXPIXEL....The maximum number of pixels that are searched for components inside the ``AP'' in each major cycle. < 1000 => 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 caution, but big wins are possible using larger sizes on very large cleans. Can be changed by TELL. DOTV........Display residuals on TV channel 1. >= 0 => yes. If true, you may stop the CLEANing with TV button D after each residual map is displayed. Can be reset with TELL. 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. ---------------------------------------------------------------- APCLN: Task which cleans an image using the BGC-AP algorithm DOCUMENTOR: Alan Bridle (NRAO-Charlottesville) RELATED PROGRAMS: UVMAP,ASCAL,UVSUB,CCMOD,PRTCC,VBCC,VM PURPOSE APCLN deconvolves a dirty beam from a dirty map image using the CLEAN algorithm [Hogbom 1974] as modified to take advantage of the Array Processor [Clark 1980]. CLEAN iteratively constructs discrete approximants F(n) to a solution F of the convolution equation: B^F = D (1) where D denotes the discrete representation of the dirty map and B of the dirty beam, the symbol ^ here denoting convolution. The initial approximant F(0)=0 everywhere. At the n'th iteration, CLEAN searches for the extremum of the residual mapR determined at the (n-1)'th iteration: R(n-1) = D - B^F(n-1) (2) A delta-function "CLEAN component", centered at this extremum, and of amplitude g (the loop GAIN) times its value, is added to F(n-1) to yield F(n). The search over R is restricted to an area A called the "CLEAN window". A is specified as a number NBOXES of rectangular sub-areas, or CLBOXes. Iterations continue until either the number of iterations n reaches a preset limit N (=ABS(NITER)), or the absolute value of the extremum in the CLEAN window of the residual map decreases to a preset value FLUX. If NITER is negative then the CLEAN will stop at the first negative component. This option should be used with caution and never be used on the last CLEAN of an image. CLEAN uses negative components to correct when too much flux has been subtracted from a pixel and does not necessarily mean that the noise has been reached. To diminish any spurious high spatial frequency features in the solution, F(N) is normally convolved with a "hypothetical" Gaussian "Clean Beam" H to construct a final "Clean Map" C: C = H^F(N) + R(N) (3) The clean beam H may be specified by the user through the parameters BMAJ, BMIN, BPA, or it may be defaulted to an elliptical Gaussian fitted to the central region of the dirty beam B. APCLN writes the array of "Clean Components" F(N) to the CC extension of the clean map image file. The Clark algorithm speeds up the deconvolution process by splitting it into "major" and "minor" iteration cycles. At the beginning of the m'th major cycle, it loads into the AP a RESTRICTED residual map R'(m) containing only the LARGEST (positive and negative) values in the current residual map R(m). It then performs a "minor" cycle of iterations wherein new CLEAN components are sought with (a) the restricted residual map R'(m) replacing the full residual map R and (b) the dirty beam B being approximated by its values inside a small area (the "beam PATCH") with zeroes outside. A minor cycle is terminated at iteration n' when the peak in the restricted residual map R'(n') falls to a given multiple [Clark 1980] of the largest value that was ignored in R(m) when R'(m) was passed to the the AP. At the end of the cycle of minor iterations, the current clean component list F(n') is Fourier transformed, multiplied by the transform of the beam B, transformed back into the map plane, and then subtracted from the dirty map D, thereby performing step (2) EXACTLY with the components list F(n') obtained at the end of the minor cycle. Errors introduced in the minor cycle through use of the restricted beam patch are corrected to some extent at this step. This ends the m'th major cycle, the (m+1)th beginning when the new restricted residual map R'(m+1) is loaded into the AP. CLEANing ends (with the transform steps used at the end of a major cycle) when either the total number of minor iterations reaches NITER, or the residual value being CLEANed at a minor iteration reaches FLUX. An alternative Maximum entropy deconvolution program is available in AIPS as task VM but it is experimental and slow. COMMENTS Don't Run APCLN ... =================== If there is so little signal in your map that no sidelobes of any source in it exceed the thermal noise, then no sidelobe deconvolution is necessary, and running APCLN is a waste of your time and of CPU cycles. General - You can help APCLN when you run UVMAP =============================================== Other things being equal, the accuracy of the deconvolution process is greatest when the shape of the dirty beam is well sampled. When mapping complicated fields, it is often necessary to compromise between cell size and field of view; if you are going to CLEAN a map image, you should set up your parameters in UVMAP so that there will be at least three or four cells across the main lobe of the dirty beam. It is also important to make the map size large enough that no strong sources whose sidelobes will affect your map have been aliased by the FFT (preventing APCLN from handling them correctly). Consider making a strongly tapered map of a wide field around your source at low resolution to diagnose confusion before running APCLN on a high resolution map (especially when processing snapshot data from the lower VLA frequencies). It is helpful to regard CLEAN as an attempt to interpolate missing samples in the (u,v) plane. The accuracy of the interpolation is greatest where the original sampling is dense or where the visibility function varies slowly. The accuracy is least where you ask CLEAN to EXTRApolate into poorly sampled or unsampled regions of the (u,v) plane where the visibility function changes rapidly. One such region is the center of the (u,v) plane in any VLA map made from data where all of the fringe visibilities were less than the integrated flux density of the source. You can help CLEAN to guess what may have happened in the center of the (u,v) plane (and thus to guess what the more extended structure on your map should look like) by including a zero-spacing flux density when you make your map with UVMAP. This gives CLEAN a datum to "aim at" in the center of the (u,v) plane. Extended structure can often be reconstructed well by deep CLEANing when the zero-spacing flux density is between 100% and 125% of the average visibility amplitude at the shortest spacings. If your data do not meet this criterion, there may be no RELIABLE way for you to reconstruct the more extended structure. (Some cases with higher ratios of zero-spacing flux density to maximum visibility amplitude can be successfully CLEANed, but success is difficult to predict). If you see an increase in the visibility amplitudes on the few shortest baselines in your data, but not to near the integrated flux density, you may get better maps of the FINE structure from APCLN by excluding these innermost baselines when you run UVMAP. Another unsampled region lurks in the outer (u,v) plane in many VLA maps of sources at declinations south of +50, if the source has complicated fine structure. To see why, consult the plots of (u,v) coverage for the VLA in Section 4 of the "Green Book" [Hjellming 1982]. At lower declinations, some sectors of the outer (u,v) plane are left poorly sampled, or unsampled, even by "full synthesis" mapping. (There are missing sectors in the outer (u,v) plane in ANY snapshot map). If the visibility function of your source has much structure in the unsampled sectors, CLEAN may work poorly on a high resolution map unless it gets good "clues" about the source structure from the well-sampled domain. If the clues are weak, badly extrapolated visibilities in the unsampled regions can cause high frequency ripples on the CLEAN map. In such cases, CLEAN may give maps with better dynamic range if you are not too resolution-greedy, and restrict your data to the well-sampled "core" of the (u,v) plane when you run UVMAP. Before applying CLEAN, examine your (u,v) coverage and think whether you will be asking the algorithm to guess what happened in such unsampled regions. Frailties, Foibles and Follies ============================== There are excellent discussions of CLEAN's built-in idiosyncracies by Schwarz (1978, 1979), by Clark (1982) and by Cornwell (1982). Another way of looking at CLEAN is to think of it as attempting to answer the question "What is the distribution of amplitudes at the CLEAN component positions [F(N)] which best fits the visibility data, if we define the sky to be blank everywhere else ?" The algorithm can then be thought of as a "search" for places where F should be non-zero, and an adjustment of the intensities in F(N) to obtain the "best" agreement with the data. The reconvolution of F(N) with the hypothetical "clean beam" H produces a "clean map" C whose transform is no longer a "best fit" to the data (due to differences between the transforms of H and of the dirty beam B). The merit of the reconvolution is that it produces maps whose noise properties are pleasing to the eye. It may also be used to "cover up" instabilities in CLEAN stemming from poor extrapolation into the unsampled regions of the (u,v) plane, by making H significantly wider than the main lobe of B. Note also that step (3) of the standard CLEAN combines this reconvolution with the residual map, which contains faint sky features convolved with the DIRTY beam B. If there is significant signal remaining in the residual map, the effective resolution of the Clean Map C varies with brightness. You must therefore be particularly careful when comparing Clean maps made at different frequencies or in different polarizations; you should CLEAN all such maps sufficiently deeply that the integrated flux density in the CLEAN components F(N) is much greater than that in the residual map R(N). A recurrent question about CLEAN concerns the uniqueness of the Clean Map. In the absence of noise, CLEAN could adjust the amplitudes of the components in F(N) to minimize the rms difference between the observed visibility function and the transform of F(N) [Schwarz 1978, 1979]. If the number of degrees of freedom in F(N) is less than the number in the data, CLEAN can (and in many practical cases does) converge on a solution that is sensibly independent of your input parameters. Noise and approximations in the algorithms complicate this [Cornwell 1982], but realise that the solution CANNOT be unique if the number of positions at which you end up with CLEAN components exceeds the number of independent (u,v) data points. Be suspicious if your Clean Map contains structures which resemble those of the dirty beam. This may mean either that you have not CLEANed deeply enough, or that APCLN has had difficulty in some unsampled sector of the (u,v) plane in your case. This test is particularly important in the case of snapshot maps, for which the sidelobes of the dirty beam have a pronounced star (snowflake) structure. GAIN and NITER The depth to which APCLN carries out its deconvolution is approximately measured by the product NITER*GAIN. The value of NITER and the execution time needed to reach a given CLEANing depth are minimized by setting GAIN = 1.0, but setting GAIN > 0.5 is recommended only when removing the sidelobes of a single bright unresolved component from surrounding fainter structure. When CLEANing diffuse emission, GAIN = 0.1 (the default) will be much better, for the following reason. The search step of the algorithm begins its work at the highest peak (which in an extended source may be a random noise "spike"). After one iteration, the spike is replaced in R by a negative beamshape, so the next highest peaks are more likely to be found where the spike would have had its biggest negative sidelobes [see the diagram on p.11 of Clark (1982)]. If GAIN is high, subsequent iterations tend to populate F(n) around the negative sidelobe regions of the highest peaks. This "feedback" can be turned off by making GAIN small enough that the negative sidelobes of the first peaks examined in an extended structure are lost in the noise, i.e. GAIN * (worst negative sidelobe level) < signal-to-noise on the extended structure. In practice setting GAIN << 0.1 makes APCLN unacceptably slow (NITER too large for a given CLEANing depth) so a compromise is needed. GAINs in the range 0.1 to 0.25 are most commonly used. If the source has some very bright compact features embedded in weaker diffuse emission, it is illuminating to examine the Clean Map when only the brightest structure has been CLEANed, to check whether subsequent CLEANing of weaker diffuse emission causes it to "go lumpy" via the sidelobe feedback effect. This could be done with GAIN = 0.3-0.5, using either NITER or the CLBOX selection to ensure that the search does not stray into the extended emission. Then APCLN can be restarted with lower GAIN, higher NITER and wider CLBOXes to tackle the diffuse structure. If the weak emission "goes lumpy" you may need to rerun APCLN with different combinations of GAIN and NITER to find the most effective one for your particular case. Ultimately you will stop APCLN when the new CLEAN component intensities approach the noise level on your map. On a map of Stokes I, the appropriate stopping point will be indicated by comparable numbers of positive and negative components appearing in the CC list. On maps of Stokes Q and U, which can and will be legitimately negative, you need to know the expected sensitivity level of your observation to judge how deep to go. It is NEVER worth increasing NITER and restarting APCLN once many negative CLEAN components appear in the CC list of an I map. When this occurs, you are using APCLN to shuffle the noise in the residual map, which is about as sensible as rearranging the deck chairs on the Titanic after it hit the iceberg. FLUX This provides an alternative to NITER for terminating the iterations in a given run of APCLN. In practice, most users prefer to control APCLN by limiting each execution with NITER. FLUX should then be set to your expected rms noise level times the dynamic range of the dirty beam (peak/worst sidelobe), to ensure that you do not inadvertently waste time iterating to a high value of NITER while in fact CLEANing emission whose sidelobes are lost in the noise. The FLUX criterion is applied only to the residuals inside the CLEAN window. PHAT When dealing with two-dimensional extended structures, CLEAN can produce artifacts in the form of low-level high frequency stripes running through the brighter structure. These stripes derive from poor interpolations into unsampled or poorly sampled regions of the (u,v) plane. [When dealing with quasi one-dimensional sources (jets), the artifacts resemble knots (which may not be so readily recognized as spurious)]. APCLN can invoke a modification of CLEAN that is intended to bias it towards generating smoother solutions to the deconvolution problem while preserving the requirement that the transform of the CLEAN components list fits the data. The mechanism for introducing this bias is the addition to the dirty beam of a delta-function (or "spike") of small amplitude (PHAT) while searching for the CLEAN components. [The beam used for the deconvolution thereby resembles the helmet worn by German military officers in World War I, hence the name "Prussian Helmet Clean"]. The theory underlying the algorithm is given by Cornwell (1982, 1983), where it is described as the Smoothness Stabilized CLEAN (SSC). PHAT has given good results in some cases (e.g. Sag A at 20cm - see Cornwell 1983), reducing the amplitude of fringelike artifacts and producing more believable images. If you think APCLN has left CLEAN artifacts in what should be a smooth source, you have nothing to lose, and possibly something to gain, by using PHAT for comparison purposes. Tim Cornwell recommends that lower loop gains than normal, and deeper CLEANing than normal, be used when using PHAT. Use GAIN = 0.05 where you would have used 0.1 in the regular APCLN, for example. He also notes that his original recommendation for PHAT = **2/2***2 may not be optimal, and that values in the range 0.1 to 0.50 generally give the best results. Be prepared to experiment with different settings and to judge the results (severity of stripes, overall dynamic range) for yourself. PHAT will not eliminate stripes demanded by (bad ?) data. The frequency of, and reasons for, PHAT's successes and failures are not yet well understood. Your description of any results (good or bad) attending use of PHAT will therefore be appreciated by the AIPS group and by Tim Cornwell. BITER The default (BITER=0) restarts the CLEAN from scratch. Other values of BITER are used when APCLN is to be restarted from an intermediate step in the process. When set >0, it specifies the number of components from a previous clean to be subtracted from the dirty map to obtain the residual map for the first new iteration. Restarts are sometimes needed after the computer has crashed during a long CLEAN. Under these circumstances, the iteration number at the end of the last major cycle is stored in the AIPS file header. Provided that the crash has not destroyed relevant image files (or the CC extension file) on disk, the CLEAN may be restarted by setting BITER equal to the number of iterations shown in the image header for the CLEAN map - if this disagrees with the number in the internal file header (as may happen if the crash comes at an unfortunate point in a cycle), AIPS will adjust BITER downwards in a "fail-safe" way. (PRTCC might be run to check the state of the components list in such cases). When you set BITER>0, you must set the OUTNAME and OUTSEQ parameters explicitly to those of the Clean Map whose CC extension file contains the components which are to be subtracted. This Clean Map file will be overwritten by the new Clean Map when APCLN finishes, so if you wish to preserve it you should either write it to tape using FITTP or create a second copy of it on disk using SUBIM. A components file F(N) can be reconvolved with a different Clean Beam H by restarting APCLN with NITER=BITER=n. This is an effective tool for making SMALL changes the resolution of a Clean Map. Do NOT use it for making large (factors >2) changes in resolution, e.g. to "find" extended components of a source. If a structure has been resolved out over the longer baselines, these baselines contribute only noise, not signal, to maps of that structure, and should be excluded from any search for the structure. CLEANing a noisy map and then convolving it to much lower resolution makes no sense. In such cases, you should remap with an appropriate taper and run APCLN on a dirty map with a more appropriate resolution. BITER may be set <0, in which case APCLN will not subtract the specified components before starting, but WILL restore them. This strategem is useful only when the input map is a RESIDUAL map, rather than a Clean map (see BMAJ). BMAJ, BMIN, BPA The default values of 0 for these parameters invoke an algorithm whereby the central portion of the dirty beam B is fitted with an elliptical Gaussian function whose parameters are then used to specify the Clean Beam H. The algorithm can be "fooled" by positive or negative sidelobes near the main lobe of B, and has been known to prescribe unsatisfactory forms for H, particularly for snapshot maps. It is normally preferable to specify BMAJ, BMIN and BPA explicitly from your own examination of the dirty beam, or after a trial fit using the default. The Clean Map C may be easier to interpret if BMIN is set equal to BMAJ, so that H 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 in F(N) 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 F(N) and from R(N) at step (3) will have greatly different resolutions. This is very dangerous if R(N) contains significant residual emission. If BMAJ is set <0, then the output map contains the residual map R(N) instead of the clean map C. This option allows you to display, take hard copy of, or back up, the residual map while deciding further strategy, retaining the ability to regenerate the Clean Map later by using BITER <0. NBOXES, CLBOX (TVBOX) These parameters specify the size and location of the rectangular boxes comprising the "CLEAN Window" area A. You make the best use of prior knowledge about the source to help APCLN do its job when you restrict A as closely as possible to the true boundaries of its emission. Recall that CLEAN attempts to optimize F(n) as a representation of the sky, with zeroes everywhere else. The more information you provide about where the "real" emission is, the more likely APCLN is to converge on a unique, credible solution. The verb TVBOX may conveniently be used to set the BLC and TRC limits of the boxes after NBOXES has been typed in. Following a prompt on your terminal, position the TV cursor at the BLC of the first CLBOX and press any trackball button. Then position the cursor at the TRC of this box and press button B. Repeat this for all desired boxes. This will fill the CLBOX array for the APCLN inputs. The terminal prompt will also give instructions for resetting any previously set corners should you need to do so. A practical detail: when NBOXES=1 and CLBOX specifies an area <= 127 by 127, the entire residual map can be loaded into an AP with 64k, and APCLN can proceed very efficiently. This speeds up execution enormously. If NBOXES>1, even if the area in the CLBOXes adds up to less than 127 by 127, this economy is lost. The default [NBOXES=1, CLBOX=0] specifies that the inner quarter of the map is to be searched for CLEAN components. A particularly large economy in run time is achieved when this default is used with 256 by 256 (or smaller) maps. In the 256 by 256 case not only will the Clean Window default to 127 by 127 (it's crafty enough to prune down the nominal 128 by 128) but the necessary FFTs can be done entirely within the AP; under these circumstances APCLN proceeds at a headlong gallop (about 4 minutes for 1000 iterations). No more than the inner quarter of the map can be CLEANed accurately (due to the limited area over which the dirty beam is known). APCLN will however try to CLEAN a bigger area if you ask it to, and will succeed to a level of approximation which gets worse as you approach the edge of the map. Use this naivety of APCLN sparingly and with caution - it will never do well in the outer 10% of the dirty map. FACTOR This knob protrudes from the inner workings of the Clark algorithm, enabling the user to vary the criterion [Clark 1980] by which minor iteration cycles are ended. [For those with an interest in the gory details - APCLN first notes the ratio between the brightest point which was ignored when the residual map R'(m) was passed to the AP and the maximum residual R'(n') at some later iteration n'; it then uses the Clark criterion with this ratio raised to the power FACTOR replacing unity in Clark's summation]. FACTOR = 0 (the default) recovers the Clark criterion. FACTOR > 0 allows the minor cycles to go on longer, speeding up the CLEAN slightly (about 20% for FACTOR = 1), but allowing you to get closer to the situation where residuals R' in the AP become smaller than values which were ignored when the AP was loaded. The search for new components becomes less and less accurate (compared with a Hogbom algorithm using all of R in step (2)), and the representation of extended structure in the final F(N) deteriorates. FACTOR < 0 makes the termination criterion more conservative and thus improves the accuracy of the CLEANing at the expense of forcing more major cycles with a corresponding overhead in the FFTs done at the end of each one. It is recommended that experiments with FACTOR normally be confined to the range -0.3 < FACTOR < +0.3, negative values being used when CLEANing complex extended structures, and positive values when CLEANing very simple compact structures. MINPATCH This parameter specifies the minimum half-width of the beam patch that will be allowed in a minor cycle. A smaller beam patch allows the CLEAN to go faster at the expense of less accurate subtraction at each iteration. The inaccuracy can lead to errors which will not be recovered completely at the end of the major cycle, especially if high GAINs are used or the source has complex structure. MINPATCH=51 is recommended for CLEANing complicated sources, but larger sizes up to 1024 should be used for complicated (poor) dirty beams (i.e. VLA snapshots, VLBI). DOTV Use of DOTV > 0 is STRONGLY recommended when CLEANing a source for the first time. It causes the residual map to be displayed on the TV after each major cycle, allowing you to monitor what emerges as the CLEAN progresses. DOTV > 0 produces a 15-sec pause after each major cycle to give you time to inspect the display and to assess whether it is reasonable to proceed. Pressing trackball D during this pause terminates APCLN in an orderly fashion. Pressing buttons A,B,C (or allowing the pause time to elapse) starts the next major cycle. When CLEANing a very complicated source for the first time, it is often worth going beyond this interactive approach, by taking hard copy of various stages of the CLEAN to compare carefully later. Consider setting NITER to a value in the range 50-200 at first (the default is 200). Then take hard copy of the lightly CLEANed map for later reference, and restart APCLN with a higher value of NITER. Doing this increasing NITER by factors of order 2 each time can be very instructive in showing you what APCLN is doing to the extended structures in your source. Spectral line users may wish to CLEAN a typical channel in this way before deciding how best to parameterize APCLN for their production runs. (Note that the trial channel should be reanalysed using the final choice of parameters, for consistency; APCLN's final Clean maps depend in detail on the relative numbers of major and minor cycles which have been performed). Prudence If running APCLN on a complicated source with low GAIN you may need to work to large final values of NITER. As APCLN is the major consumer of CPU time in most map analyses, it is prudent to preserve intermediate clean maps by writing them to a FITS tape with FITTP. This allows you to recover from disasters such as crashes, overCLEANing, etc. with minimal impact on total execution time, your time, and on disk space. Considerations for CLEANing Cubes Spectral line cubes and other multidimensional images may now be CLEANed one plane per run of APCLN. 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. If the beam image is also a cube then the corresponding plane for the beam will be used otherwise the first (only) plane will be used. 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. Considerations for assymmetric beams APCLN partially supports the use of assymetric beams. The routine that finds the components (minor cycles) uses only half of the beam and assumes that it is symmetric. At the end of major cycles the components are subtracted with the proper beam. Thus, it is desirable that a CLEAN with an assymmetric beam take several major cycles. For large images this is no problem but for small images the use of a several CLEAN boxes may be useful even if one is small and contains nothing of interest. Also the adverb FACTOR can be used to reduce the number of components per major cycle; a value of -1 may be a good starting guess. More major cycles should be used for more strongly assymmetric beams. Note, beam means the same thing as point spread function. Timing ====== As described above, APCLN runs enormously faster when the Clean Window is <= 127 by 127 and the map is <=256 by 256 than when only fractions of the residual map can be stored in the AP and large FFTs are required. CPU times for these small CLEANs will be only a few minutes for several thousand iterations. When bigger maps and Clean Windows are required, APCLN's run times become harder to predict. The steps involved in the major cycles are the most consumptive, so the number of major cycles required to do the CLEAN dominates the CPU time. The number of major cycles required depends on the complexity of the source, but CLEANs involving 10,000 components or so will often chew through five or six of them. As APCLN is the main CPU hog in AIPS, you should not run APCLN on large maps (>512) with more than about 5000 iterations without estimating run times for your case from more modest initial CLEANs. Also look at the components file to check the need for such deep CLEANing before turning APCLN loose on this scale. On a VAX 11-780 with an FPS 120B array processor the run time in an otherwise empty machine is 3.0 * (M / 1024) **1.5 min to get maps 2.0 * (M / 1024) **2.0 min to find 1000 comp. 3.2 * (M / 1024) **1.5 min each major cycle 2.0 * (M / 1024) **2.0 min store maps where M is the map size. For example cleaning the inner quarter of a 1024 x 1024 map for 1000 iterations (assuming 4 major cycles) is about 20 min run time. If the machine is busy the run time may be substantially longer. REFERENCES Clark, B.G. (1980). "An Efficient Implementation of the Algorithm "CLEAN", Astron.Ap., 89, 377-378 Clark, B.G. (1982). "Large Field Mapping", Lecture #10 in the NRAO-VLA Workshop on "Synthesis Mapping" Cornwell, T.J. (1982). "Image Restoration (and the CLEAN Technique)", Lecture #9 in the NRAO-VLA Workshop on "Synthesis Mapping" Cornwell,T.J. (1982). "Can CLEAN be Improved ?", VLA Scientific Memorandum No. 141. Cornwell,T.J. (1983). "A Method of Stabilising the CLEAN Algorithm", preprint. Hjellming,R.M. (1982). "An Introduction to the NRAO Very Large Array", Section 4. Hogbom,J.A. (1974). "Aperture Synthesis with a Non-Regular Distribution of Interferometer Baselines",Astron.Ap.Suppl., 15, 417-426 Schwarz, U.J. (1978). "Mathematical-statistical Description of the Iterative Beam Removing Technique", Astron.Ap.,65, 345. Schwarz, U.J. (1979). "The Method "CLEAN" - Use, Misuse and Variations", in Proc. IAU Colloq. No.49, "Image Formation from Coherence Functions in Astronomy", ed. C. van Schooneveld, (Dordrecht:Reidel), p. 261-275.