AUTOCUBE_V1.PY The autocube function iteratively cleans a spectral line image in CASA, one channel at a time, using an auto-boxing algorithm similar to that outlined in AIPS Memo #115. Autocube is similar to autoclean, except that it is written to handle spectral line data (a data cube). (Autocube supercedes autoclean, which is now merely a special case of the new autocube.) Autocube cleans one channel at a time, searching efficiently for new clean regions each time. For each channel, it starts by creating a dirty image from which it chooses initial clean boxes. It then cleans using CASA's CLEAN task, chooses more boxes if necessary, and continues in this fashion until it reaches a stopping point, determined by the user's input parameters, when it moves onto the next channel. Finally, it concatenates the channels into a single, final set of images. It then writes a "saved" file with input parameters for CLEAN, such that the image can be CLEANed from the start using the final autocube mask. Note: it is possible for the user to input an initial mask (file, region, or boxes) which will be used to initiate the mask of each channel. Autocube is currently written as a python function. To use autocube in CASA, put the autocube_v1.0.py into your python path. Then: CASA : import autocube_v1 CASA : autocube_v1.autocube( ) This program is under development. We welcome your comments: akimball@nrao.edu HOW NEW CLEAN REGIONS ARE CHOSEN IN EACH CHANNEL (and some important input parameters) 1. Select potential clean regions by finding "islands": contiguous sets of pixels above some threshold value (similar to the ISLAND procedure developed for AIPS). The threshold is equal to 'island_rms' * rms, where rms is the current rms in the residual image (outside of the current clean regions), and 'island_rms' is an input parameter with a default value of 4. 2. Narrow down potential clean regions further by making selections based on the peak pixel in each island. Islands are rejected if their peak pixel is less than the maximum of ('peak_rms' * rms; 'gain_threshold' * max_residual), where rms is the rms in the residual image outside of the current clean regions, max_residual is the current maximum residual 'peak_rms' is an input parameter with a default value of 6, and 'gain_threshold' is an input parameter with a default value of 0.1. Islands are also rejected if they are one pixel wide in either direction, unless the peak is more than 2.5 times the larger of the two cutoffs given earlier in this paragraph. 3. The brightest 'Npeak' of the remaining islands (based on their peak pixel) are retained, where 'Npeak' is an input parameter with default value of 3. 4. A new clean region is added for each island's peak which is not already in the clean mask. 5. Shape: Clean regions can be circles, boxes, or either, depending on the input parameter 'shape' (0 for circles, 1 for boxes, 2 for both; default value is 2). If input parameter 'shape'=2, the shape of each region is determined by the island's sizes in the x and y direction. If x and y sizes are within one pixel, the new region is a circle, otherwise it is a rectangle. 6. Size: For circular clean regions, the diameter of the circle is equal to the larger of the x and y sizes of the island and is centered on the center of the island. For rectangular clean regions, the box is placed over the island, using corners returned by the "island" procedure (see point 1 above). The size of a circular or rectangular clean region is extended outward by a number of pixels equal to 'boxstretch', an input parameter with a default value of 1. 'boxstretch' must be between -1 and 5, inclusive. WHEN DOES AUTOCUBE STOP CLEANING A CHANNEL? Autocube will continue cleaning and searching for new clean boxes until one of the following conditions is met (before moving on to the next channel): 1. The current maximum residual is less than input parameter 'clean_threshold', with a default value of 0. Parameter 'clean_threshold' gets passed to the clean task as its own input parameter 'threshold'. 2. The current maximum residual is less than 'Nrms' * rms, where rms is the rms outside of the current clean regions, and 'Nrms' is an input parameter with a default value of 6. For small images (256 X 256), a smaller value of 'Nrms'~5 is more appropriate. A value of ~6 is appropriate for 2048 X 2048. 3. The number of clean/autoboxing iterations reaches 'maxcycle', an input parameter with a default value of 20. SUMMARY OF AUTOCUBE'S INPUT PARAMETERS outputfile: redirect standard output to this file, if given. (default='') maxcycle: maximum number of clean/autobox iterations before stopping (default=20) clean_threshold: autocube stops if the current maximum residual is less than this value. Doubles as clean's input parameter 'threshold'. (default=0) Nrms: autocube stops if the current maximum residual is less than 'Nrms' * rms, where rms is determined outside of the current clean regions. (default=6) island_rms: threshold for identifying "islands", i.e. potential clean regions, made of contiguous pixels above threshold value of 'island_rms'*rms. This parameter does not affect where clean regions are placed, but it determines their size. (default=4) peak_rms: potential clean regions are rejected if their peak is less than 'peak_rms'*rms. (default=6) gain_threshold: potential clean regions are rejected if their peak is less than 'gain_threshold' * current maximum residual. Helps to keep from putting clean regions around sidelobes. (default=0.1) Npeak: maximum number of new clean regions added in each iteration. (default=3) shape: determines shape of clean regions. 0 = all circles. 1 = all rectangles. 2 = circle or rectangle, depending on intrinsic shape of the "island". (default=2) boxstretch: number of pixels to increase size of clean region beyond the size of the given "island". (restricted to -1 --> 5, default=1) AUTOCUBE ALSO NEEDS CLEAN'S INPUT PARAMETERS Currently, Autocube is a python function, not a CASA task. Thus any CLEAN task parameters (other than the default values) must be passed to autocube as input parameters. Autocube_v1 supports the following CLEAN input parameters: vis, imagename, field, spw, selectdata, mode, nchan, start, width, interpolation, niter, gain, psfmode, imagermode, cyclefactor, cyclespeedup, imsize, cell, phasecenter, restfreq, weighting, robust, npixels. Other CLEAN task parameters which will remain at the default values (for now): multiscale=[], interactive=False, mask=[], stokes='I',uvtaper=False, modelimage='', restoringbeam=[''], pbcor=False, minpb=0.1, async=False CLEAN's threshold parameter is set with autocube input parameter clean_threshold (see above). EXAMPLE USING A VLA IMAGE OF NGC5921 Demo link: http://casa.nrao.edu/Doc/Scripts/ngc5921_demo.py After running the demo, you can run autocube on the calibrated data using, for example, the following parameters (channel mode): vis = 'ngc5921.demo.src.split.ms.contsub' imagename = 'ngc5921.autoclean.channel' outputfile = imagename+'.out' autocube_v1.autocube( vis=vis, imagename=imagename, island_rms=4, peak_rms=6, Npeak=1, gain_threshold=0.3, clean_threshold=0, Nrms=5, niter=50, maxcycle=10, shape=2, boxstretch=3 psfmode='hogbom', imagermode='csclean', cell=[15,15], imsize=[256,256], weighting='briggs', robust=0.5, mode='channel', start=5, nchan=46) The "saved" file will be imagename+'.final.saved'. To clean with the final mask: default(clean) imagename = 'ngc5921.autoclean.channel' execfile(imagename+'.final.saved') clean() -------------------------------------------------------------- Suggested parameters to run in 'velocity' mode: vis = 'ngc5921.demo.src.split.ms.contsub' imagename = 'ngc5921.autoclean.channel' outputfile = imagename+'.out' autocube_v1.autocube( vis=vis, imagename=imagename, island_rms=4, peak_rms=6, Npeak=1, gain_threshold=0.3, clean_threshold=0, Nrms=5, niter=50, maxcycle=10, shape=2, boxstretch=3 psfmode='hogbom', imagermode='csclean', cell=[15,15], imsize=[256,256], weighting='briggs', robust=0.5, mode='velocity', start='1506km/s', width='5km/s', nchan=20) -------------------------------------------------------------- Suggested parameters to run in 'velocity' mode: vis = 'ngc5921.demo.src.split.ms.contsub' imagename = 'ngc5921.autoclean.channel' outputfile = imagename+'.out' autocube_v1.autocube( vis=vis, imagename=imagename, island_rms=4, peak_rms=6, Npeak=1, gain_threshold=0.3, clean_threshold=0, Nrms=5, niter=50, maxcycle=10, shape=2, boxstretch=3 psfmode='hogbom', imagermode='csclean', cell=[15,15], imsize=[256,256], weighting='briggs', robust=0.5, mode='velocity', start='1.4128GHz', width='30kHz', nchan=35) -------------------------------------------------------------- Note: When running CLEAN using autocube's mask file and with the ".final.saved" parameters, some channels can diverge resulting in poor results. Reducing the cleaning depth, such as setting "cyclefactor = 2" (default value is 1.5) can help alleviate this problem.