Difference between revisions of "Clean"

From CASA Guides
Jump to: navigation, search
Line 1: Line 1:
 
== Help on clean task: ==
 
== Help on clean task: ==
 
<pre>
 
<pre>
Deconvolve an image with selected algorithm
+
Invert and deconvolve images with selected algorithm
  
       This is the main clean deconvolution task.  It contains many functions
+
       The clean task has many options:
 
   
 
   
 
         1)  Make 'dirty' image and 'dirty' beam (psf)
 
         1)  Make 'dirty' image and 'dirty' beam (psf)
Line 10: Line 10:
 
         4)  Mosaicking of several pointings
 
         4)  Mosaicking of several pointings
 
         5)  Multi-scale cleaning
 
         5)  Multi-scale cleaning
         6)  Interactive clean boxing
+
         6)  Widefield cleaning
         7)  Use starting model (eg from single dish)
+
        7)  Interactive clean boxing
 +
         8)  Use starting model (eg from single dish)
 
   
 
   
 
   
 
   
Line 32: Line 33:
 
       outlierfile --- Text file name which contains image names, sizes, field
 
       outlierfile --- Text file name which contains image names, sizes, field
 
                       centers
 
                       centers
       field -- Select fields in mosaic.  Use field id(s) or field name(s).
+
       field -- Select fields to image or mosaic.  Use field id(s) or name(s).
 
                   ['go listobs' to obtain the list id's or names]
 
                   ['go listobs' to obtain the list id's or names]
 
               default: ''= all fields
 
               default: ''= all fields
Line 43: Line 44:
 
                 field = '3,4C*'; field id 3, all names starting with 4C
 
                 field = '3,4C*'; field id 3, all names starting with 4C
 
       spw -- Select spectral window/channels
 
       spw -- Select spectral window/channels
               NOTE: This selects the data passed as the INPUT to mode
+
               NOTE: channels de-selected here will contain all zeros if
 +
              selected by the parameter mode subparameters.   
 +
              Channel selection behaves differently in clean (e.g. The multiple
 +
              ranges are not supported yet).
 
               default: ''=all spectral windows and channels
 
               default: ''=all spectral windows and channels
 
                 spw='0~2,4'; spectral windows 0,1,2,4 (all channels)
 
                 spw='0~2,4'; spectral windows 0,1,2,4 (all channels)
Line 49: Line 53:
 
                 spw='<2';  spectral windows less than 2 (i.e. 0,1)
 
                 spw='<2';  spectral windows less than 2 (i.e. 0,1)
 
                 spw='0,10,3:3~45'; spw 0,10 all channels, spw 3,  
 
                 spw='0,10,3:3~45'; spw 0,10 all channels, spw 3,  
                                  channels 3 to 45.
+
                                    channels 3 to 45.
 
                 spw='0~2:2~6'; spw 0,1,2 with channels 2 through 6 in each.
 
                 spw='0~2:2~6'; spw 0,1,2 with channels 2 through 6 in each.
                 spw='0:0~10;15~60'; spectral window 0 with channels
+
                  
                                    0-10,15-60
+
                           
                spw='0:0~10,1:20~30,2:1;2;3'; spw 0, channels 0-10,
 
                      spw 1, channels 20-30, and spw 2, channels, 1,2 and 3
 
 
       selectdata -- Other data selection parameters
 
       selectdata -- Other data selection parameters
 
               default: True
 
               default: True
Line 96: Line 98:
 
                   Check 'go listobs' to insure the scan numbers are in order.
 
                   Check 'go listobs' to insure the scan numbers are in order.
 
       mode -- Frequency Specification:
 
       mode -- Frequency Specification:
               NOTE: See examples below:
+
               NOTE: Channels deselected with spw parameter will contain all
 +
                    zeros.
 +
              See examples below.
 
               default: 'mfs'
 
               default: 'mfs'
 
                 mode = 'mfs' means produce one image from all  
 
                 mode = 'mfs' means produce one image from all  
 
                       specified data.
 
                       specified data.
 
                 mode = 'channel'; Use with nchan, start, width to specify
 
                 mode = 'channel'; Use with nchan, start, width to specify
                        output image cube. See examples below
+
                        output image cube.  
                 mode = 'velocity', means channels are specified in  
+
                 mode = 'velocity', channels are specified in velocity.
                      velocity.
+
                 mode = 'frequency', channels are specified in frequency.
                 mode = 'frequency', means channels are specified in  
 
                      frequency.
 
  
 
   >>> mode='mfs' expandable parameters  
 
   >>> mode='mfs' expandable parameters  
 
               Make a continuum image from the selected frequency
 
               Make a continuum image from the selected frequency
 
               channels/range using Multi-frequency synthesis
 
               channels/range using Multi-frequency synthesis
               algorithm for wide-band narrow field imaging.
+
               algorithm for wide-band narrow field imaging. nterms
               nterms is the number of Taylor terms to be used to
+
               is the number of Taylor terms to be used to model the
               model the frequency dependence of the sky emission.
+
               frequency dependence of the sky emission. nterms=1 is
              nterms=1 is equivalent to assuming no frequency
+
              equivalent to assuming no frequency dependence.
               dependence.  nterms=2 is equivalent to the
+
               nterms=2 is equivalent to the Sault-Wieringa algorithm
              Sault-Wieringa algorithm (AandAS, 1994)
+
              (AandAS, 1994) reffreq is the reference frequency about
              reffreq is the reference frequency about which the
+
              which the Taylor expansion is done. ** Note that the
              Taylor expansion is done.
+
              software implementation of the algorithm for nterms>1
 +
              is still experimental and will be fully available in a
 +
              later release. **
  
   >>> mode expandable parameters (for modes other than 'mfs')
+
   >>> mode='channel', 'velocity', and 'frequency' expandable parameters
              Start, width are given in units of channels, frequency  
+
               nchan -- Total number of channels in the output image.
                  or velocity as indicated by mode (note: only nearest neighbour
+
                 Example: nchan=100.
                  interpolation is available at this time).
+
                Default: -1; Automatically selects enough channels to cover
               nchan -- Number of channels (planes) in output image
+
                data selected by 'spw' and consistent with 'start' and 'width'.
                 default: 1; example: nchan=3
+
                It is often easiest to leave nchan at the default value.
               start -- Start input channel (relative-0)
+
               start -- First channel, velocity, or frequency.
                 default=0; example: start=5
+
                For mode='channel'; This selects the channel index number
               width -- Output channel width in units of the input
+
                from the MS (0 based) that you want to correspond to the first
                    channel width (>1 indicates channel averaging)
+
                channel of the output cube. The output cube will be in frequency
                 default=1; example: width=4
+
                space with the first channel having the frequency of the
               interpolation -- Interpolation type of spectral data when gridded on
+
                MS channel selected by start.  start=0 refers to the first
                  the uv-plane
+
                channel in the first selected spw, even if that channel
                 default = 'nearest'
+
                is de-selected in the spw parameter. Channels de-selected by
                     HOWEVER, 'linear' is recommended
+
                the spw parameter will be filled with zeros if included by
               outframe -- velocity reference frame of output image (for mode='velocity' or 'frequency')
+
                the start parameter. For example, spw=3~8:3~100 and start=2
                 Options: '','LSRK','LSRD','BARY','GEO','TOPO','GALACTO','LGROUP','CMB'
+
                will produce a cube that starts on the third channel (recall 0
                 default: ''; same as input data; example: frame='bary' for Barycentric frame  
+
                based) of spw index 3, and the first channel will be blank.
               veltype -- (for mode='velocity') velocity definition
+
                example:start=5
                 Options: 'radio','optical','true' (='relativistic')
+
                 For mode='velocity' or 'frequency': default='';  
                veltype='true' (or equivalently 'relativistic')
+
                starts at first input channel of first input spw
                for velocity defined without approximations using the relativistic expression
+
                examples: start='5.0km/s', or start='22.3GHz'.
 +
               width -- Output channel width
 +
                For mode='channel', default=1; >1 indicates channel averaging
 +
                 example: width=4.
 +
                For mode=' 'velocity' or 'frequency', default=''; width of
 +
                first input channel, or more precisely, the difference
 +
                in frequencies between the first two selected channels.
 +
                (for example if channels 1 and 3 are selected with spw,
 +
                  then the default width will be the difference between their
 +
                  frequencies, and not the width of channel 1)
 +
                When not using the default, one must give units
 +
                examples: width='1.0km/s', or width='24.2kHz'.
 +
                Setting width>0 gives channels of increasing frequency for
 +
                mode='frequency', and increasing velocity for mode='velocity'.
 +
               interpolation -- Interpolation type for spectral gridding onto
 +
                the uv-plane. Options: 'nearest', 'linear', or 'cubic'.
 +
                 default = 'linear'
 +
              chaniter -- specify how spectral CLEAN is performed,
 +
                default: chaniter=False;
 +
                example: chaniter=True; step through channels
 +
                  WARNING: The interactive clean with chaniter=True for
 +
                     optical velocity mode
 +
                    (mode='velocity' and veltype='optical') is
 +
                    NOT YET IMPLEMENTED.
 +
               outframe -- For mode='velocity', 'frequency', or 'channel':  velocity
 +
                reference frame of output image
 +
                 Options: '','LSRK','LSRD','BARY','GEO','TOPO','GALACTO',
 +
                          'LGROUP','CMB'
 +
                 default: ''; same as input data
 +
                example: frame='bary' for Barycentric frame  
 +
               veltype -- for mode='velocity' gives the velocity definition
 +
                 Options: 'radio','optical'  
 
                 default: 'radio'
 
                 default: 'radio'
           examples:
+
                NOTE: the viewer always defaults to displaying the 'radio'
 +
                  frame, but that can be changed in the position tracking
 +
                  pull down.
 +
           mode='mfs' examples:
 
               spw = '0,1'; mode = 'mfs'
 
               spw = '0,1'; mode = 'mfs'
 
                   will produce one image made from all channels in spw  
 
                   will produce one image made from all channels in spw  
Line 149: Line 187:
 
                   will produce one image made with channels  
 
                   will produce one image made with channels  
 
                       (5,7,9,...,25,27)
 
                       (5,7,9,...,25,27)
 +
 +
          mode='channel' examples:
 
               spw = '0'; mode = 'channel': nchan=3; start=5; width=4
 
               spw = '0'; mode = 'channel': nchan=3; start=5; width=4
 
                   will produce an image with 3 output planes
 
                   will produce an image with 3 output planes
Line 170: Line 210:
 
               default: 'clark': Options: 'clark','clarkstokes', 'hogbom'
 
               default: 'clark': Options: 'clark','clarkstokes', 'hogbom'
 
               'clark'  use smaller beam (faster, usually good enough);
 
               'clark'  use smaller beam (faster, usually good enough);
                 for stokes images clean components peaks are searched in the I^2+Q^2+U^2+V^2 domain  
+
                 for stokes images clean components peaks are searched
               'clarkstokes' locate clean components independently in each stokes image
+
              in the I^2+Q^2+U^2+V^2 domain  
 +
               'clarkstokes' locate clean components independently in
 +
              each stokes image
 
               'hogbom' full-width of image (slower, better for poor  
 
               'hogbom' full-width of image (slower, better for poor  
 
               uv-coverage)
 
               uv-coverage)
               Note:  psfmode will be used to clean is imagermode = ''
+
               Note:  psfmode will also be used to clean if imagermode = ''
       imagermode -- Advanced imaging e.g mosaic or Cotton-Schwab clean
+
       imagermode -- Advanced imaging e.g. mosaic or Cotton-Schwab clean
 
               default: imagermode='': Options: '', 'csclean', 'mosaic'
 
               default: imagermode='': Options: '', 'csclean', 'mosaic'
 
               default ''  => psfmode cleaning algorithm used
 
               default ''  => psfmode cleaning algorithm used
  
 
   >>> gridmode='' expandable parameters
 
   >>> gridmode='' expandable parameters
 
 
               The default value of '' has no effect.
 
               The default value of '' has no effect.
 
          
 
          
 
   >>> gridmode='widefield' expandable parameters
 
   >>> gridmode='widefield' expandable parameters
 
 
               Apply corrections for non-coplanar effects during imaging
 
               Apply corrections for non-coplanar effects during imaging
 
               using the W-Projection algorithm (Cornwell et al. IEEE JSTSP
 
               using the W-Projection algorithm (Cornwell et al. IEEE JSTSP
Line 196: Line 236:
  
 
   >>> gridmode='aprojection' expandable parameters
 
   >>> gridmode='aprojection' expandable parameters
 
+
               Corrects for the (E)VLA polarization squint using the
               Correct for the (E)VLA polarization squint using the
 
 
               A-Projection algorithm (Bhatnagar et al., AandA (2008)).
 
               A-Projection algorithm (Bhatnagar et al., AandA (2008)).
 
 
               cfcache is the name of the directory to be used to cache the
 
               cfcache is the name of the directory to be used to cache the
                   convolution functions.  These functions can be reused again if
+
                   convolution functions.  These functions can be reused  
                  the image parameters are unchanged.  If the image parameters
+
                  again if the image parameters are unchanged.  If the image  
                   change, a new cache must be created (or the existing one
+
                   parameters change, a new cache must be created (or the
                  removed).  
+
                  existing one removed).  
 
 
 
               painc (in degrees) is the Parallactic Angle increment used to
 
               painc (in degrees) is the Parallactic Angle increment used to
 
                   compute the convolution functions.
 
                   compute the convolution functions.
  
 
   >>> imagermode='mosaic' expandable parameter(s):
 
   >>> imagermode='mosaic' expandable parameter(s):
               Image as a mosaic of the different pointings (uses csclean style too)
+
               Make a mosaic of the different pointings (uses csclean style
 +
              too)
 
               mosweight -- Individually weight the fields of the mosaic
 
               mosweight -- Individually weight the fields of the mosaic
 
                   default: False; example: mosweight=True
 
                   default: False; example: mosweight=True
Line 217: Line 255:
 
                   on-source); this parameter will give more weight to  
 
                   on-source); this parameter will give more weight to  
 
                   higher sensitivity fields in the overlap regions.
 
                   higher sensitivity fields in the overlap regions.
               ftmachine -- Gridding method for the image;
+
               ftmachine -- Gridding method for the mosaic;
                   Options: ft (standard interferometric gridding), sd
+
                   Options: 'ft' (standard interferometric gridding), 'sd'
                   (standard single dish) both (ft and sd as appropriate),
+
                   (standard single dish),  
                   mosaic (gridding use PB as convolution function)
+
                   and 'mosaic' (grid using PB as convolution function).
                   default: 'mosaic'; example: ftmachine='ft'
+
                   default: 'mosaic';  
                   if imagermode mosaic is chosen and ftmachine is mosaic,  
+
                   ONLY if imagermode='mosaic' is chosen and
                   heterogenous arrays like Carma or Alma are recognized
+
                  ftmachine='mosaic', is heterogeneous imaging (CARMA, ALMA)
                  and the right Primary Beam (depending on the size of the dish)
+
                   possible using the right convolution of primary beams for
                   is used for each baseline.  
+
                   each baseline.
 
               scaletype -- Controls scaling of pixels in the image plane.
 
               scaletype -- Controls scaling of pixels in the image plane.
 
                   (Not fully implemented...for now only controls  
 
                   (Not fully implemented...for now only controls  
Line 233: Line 271:
 
                   Options: 'PBCOR','SAULT'
 
                   Options: 'PBCOR','SAULT'
 
                     'SAULT' when interactive=True shows the residual
 
                     'SAULT' when interactive=True shows the residual
                             with constant noise across the mosaic. If
+
                             with constant noise across the mosaic.  
                            pbcor=False, the final output image is NOT
 
                            corrected for the PB pattern, and therefore is
 
                            not "flux correct". Division of SAULT
 
                            <imagename>.image by the <imagename>.flux image
 
                            will produce a "flux correct image", can also
 
 
                             be acheived by setting pbcor=True.
 
                             be acheived by setting pbcor=True.
 
                     'PBCOR' uses the SAULT scaling scheme for
 
                     'PBCOR' uses the SAULT scaling scheme for
 
                             deconvolution, but if interactive=True shows the
 
                             deconvolution, but if interactive=True shows the
                             primary beam corrected image; the final PBCOR
+
                             primary beam corrected image during interactive.  
                            image is "flux correct" if pbcor=True.
 
  
 
   >>> imagermode='csclean' expandable parameter(s):  
 
   >>> imagermode='csclean' expandable parameter(s):  
 
               Image using the Cotton-Schwab algorithm in between major cycles
 
               Image using the Cotton-Schwab algorithm in between major cycles
 
               cyclefactor -- Change the threshold at which the deconvolution  
 
               cyclefactor -- Change the threshold at which the deconvolution  
                   cycle will stop, degrid and subtract from the visibilities.  
+
                   cycle will stop, degrid and subtract from the visibilities   
 
                   For poor PSFs, reconcile often (cyclefactor=4 or 5);  
 
                   For poor PSFs, reconcile often (cyclefactor=4 or 5);  
 
                   For good PSFs, use cyclefactor 1.5 to 2.0.  
 
                   For good PSFs, use cyclefactor 1.5 to 2.0.  
                   Note: threshold = cyclefactor * max sidelobe * max residual.
+
                   Note: threshold = cyclefactor * max sidelobe * max residual
 
                   default: 1.5; example: cyclefactor=4
 
                   default: 1.5; example: cyclefactor=4
 
               cyclespeedup -- Cycle threshold doubles in this number of  
 
               cyclespeedup -- Cycle threshold doubles in this number of  
Line 268: Line 300:
 
               is 10" and cell=2", try multscale = [0,5,15]. Note,
 
               is 10" and cell=2", try multscale = [0,5,15]. Note,
 
               multiscale is currently a bit slow.
 
               multiscale is currently a bit slow.
               default: multiscale=[] (standard CLEAN using psfmode algorithm,
+
               default: multiscale=[] (standard CLEAN with psfmode algorithm,
 
               no multi-scale). Example:  multiscale = [0,5,15]  
 
               no multi-scale). Example:  multiscale = [0,5,15]  
  
 
   >>> multiscale expandable parameter(s):  
 
   >>> multiscale expandable parameter(s):  
               negcomponent -- Stop component search when the largest scale has
+
               negcomponent -- Stop component search when the largest scale
                  found this number of negative components; -1 means continue
+
                has found this number of negative components;
                  component search even if the largest component is
+
                -1 means continue component search even if the largest
                  negative.  default: -1; example: negcomponent=50
+
                component is negative.  default: -1; example: negcomponent=50
 
               smallscalebias -- A bias toward smaller scales.  
 
               smallscalebias -- A bias toward smaller scales.  
 
                   The peak flux found at each scale is weighted by  
 
                   The peak flux found at each scale is weighted by  
Line 329: Line 361:
  
 
   >>> interactive=True expandable parameters
 
   >>> interactive=True expandable parameters
               npercycle -- this is the  number of iterations between each clean
+
               npercycle -- this is the  number of iterations between each
                  to update mask interactively.  It is important to modify
+
                interactive update of the mask.  It is important to modify
                  this number interactively during the cleaning, starting wiht
+
                this number interactively during the cleaning, starting with
                  a low number like 20, but then increasing as more extended
+
                a low number like 20, but then increasing as more extended
                  emission is encountered.
+
                emission is encountered.
              chaniter -- specify how interactive CLEAN is performed,
 
                  either by stepping through channels or do jointly for all channel
 
                  default: chaniter='joint';
 
                  example: chaniter='channel'; step through channels
 
  
 
       mask -- Specification of cleanbox(es), mask image(s), and/or
 
       mask -- Specification of cleanbox(es), mask image(s), and/or
Line 361: Line 389:
 
               nested lists:  
 
               nested lists:  
 
                 e.g. mask=[[[110,110,150,145],'myimage.mask'],[],[20,20,40,40]]
 
                 e.g. mask=[[[110,110,150,145],'myimage.mask'],[],[20,20,40,40]]
               (A clean box with [110,110,150,145] and a image mask for main field,  
+
               (A clean box with [110,110,150,145] and a image mask for main
              no mask for 1st outlier field, 1 clean box for second outlier field.)
+
                field, no mask for 1st outlier field, 1 clean box for second
 +
                outlier field.)
 
       uvtaper -- Apply additional uv tapering of the visibilities.
 
       uvtaper -- Apply additional uv tapering of the visibilities.
 
               default: uvtaper=False; example: uvtaper=True
 
               default: uvtaper=False; example: uvtaper=True
 
 
   >>> uvtaper=True expandable parameters
 
   >>> uvtaper=True expandable parameters
 
               outertaper -- uv-taper on outer baselines in uv-plane
 
               outertaper -- uv-taper on outer baselines in uv-plane
 
                   [bmaj, bmin, bpa] taper Gaussian scale in uv or  
 
                   [bmaj, bmin, bpa] taper Gaussian scale in uv or  
                   angular units. NOTE: uv taper in (klambda) is roughly on-sky
+
                   angular units. NOTE: the on-sky FWHM in arcsec is roughly
                   FWHM(arcsec/200)
+
                   the uv taper/200 (klambda).
 
                   default: outertaper=[]; no outer taper applied
 
                   default: outertaper=[]; no outer taper applied
 
                   example: outertaper=['5klambda']  circular taper  
 
                   example: outertaper=['5klambda']  circular taper  
 
                                 FWHM=5 kilo-lambda
 
                                 FWHM=5 kilo-lambda
 
                             outertaper=['5klambda','3klambda','45.0deg']
 
                             outertaper=['5klambda','3klambda','45.0deg']
                             outertaper=['10arcsec'] on-sky FWHM 10"
+
                             outertaper=['10arcsec'] on-sky FWHM 10 arcseconds
 
                             outertaper=['300.0'] default units are meters  
 
                             outertaper=['300.0'] default units are meters  
 
                                 in aperture plane
 
                                 in aperture plane
Line 382: Line 410:
 
                   zero at uv=0
 
                   zero at uv=0
 
                   default: innertaper=[]; no inner taper applied
 
                   default: innertaper=[]; no inner taper applied
                   NOT YET IMPLEMENTED      
+
                   NOT YET IMPLEMENTED              
 
       modelimage -- Name of model image(s) to initialize cleaning. If
 
       modelimage -- Name of model image(s) to initialize cleaning. If
 
               multiple images, then these will be added together to
 
               multiple images, then these will be added together to
Line 424: Line 452:
 
               from dirty beam.  
 
               from dirty beam.  
 
               example: restoringbeam=['10arcsec'] circular Gaussian  
 
               example: restoringbeam=['10arcsec'] circular Gaussian  
                         FWHM 10" example:
+
                         FWHM 10 arcseconds example:
 
                         restoringbeam=['10.0','5.0','45.0deg'] 10"x5"  
 
                         restoringbeam=['10.0','5.0','45.0deg'] 10"x5"  
 
                         at 45 degrees
 
                         at 45 degrees
       pbcor -- Output primary beam-corrected image  
+
       pbcor -- Output primary beam-corrected image
 +
                If pbcor=False, the final output image is NOT corrected for the
 +
                PB pattern (particularly important for mosaics), and therefore is
 +
                not "flux correct". Correction can also be done after the
 +
                fact using immath to divide <imagename>.image by
 +
                the <imagename>.flux image.
 
               default: pbcor=False; output un-corrected image  
 
               default: pbcor=False; output un-corrected image  
 
               example: pbcor=True; output pb-corrected image (masked outside
 
               example: pbcor=True; output pb-corrected image (masked outside
                         minpb) Note: if you set pbcor=False, you can later
+
                         minpb)  
                        recover the pbcor image by dividing by the .flux image
+
       minpb -- Minimum PB level to use default=0.2;
                        (e.g. using immath)
 
       minpb -- Minimum PB level to use default=0.1;
 
 
               The flux image is used to determine this
 
               The flux image is used to determine this
               except for the case of mosaic with ft='mosaic'
+
               except for the case of mosaic with ftmachine='mosaic'
 
               where the flux.pbcoverage image is used.
 
               where the flux.pbcoverage image is used.
               example:
+
               example: minpb=0.01 Note: this minpb is always in effect
                        minpb=0.01 Note: this minpb is always in effect
 
 
                         (regardless of pbcor=True/False)  
 
                         (regardless of pbcor=True/False)  
 
       calready -- if True will create scratch columns if they are  
 
       calready -- if True will create scratch columns if they are  
Line 453: Line 483:
 
               1. Decide if the images will be specified directly in the
 
               1. Decide if the images will be specified directly in the
 
                 inputs or with an outlier file.  For more than a few fields,
 
                 inputs or with an outlier file.  For more than a few fields,
                an outlier file more convenient.
 
 
                Direct Method:
 
 
                  cell = ['1.0arcsec', '1.0arcsec']
 
                  imagename = ['M1_0','M1_1','M1_2]
 
                  imsize = [[1024,1024],[128,128],[128,128]]
 
                  phasecenter = ['J2000 13h27m20.98 43d26m28.0',
 
                            'J2000 13h30m52.159 43d23m08.02', 'J2000 13h24m08.16 43d09m48.0']
 
 
                Text file method  (in outlier.txt)
 
 
                  imagename = 'M1'
 
                  outlierfile = 'outlier.txt'
 
                      [phasecenter, imsize ignored]
 
 
                  Contents of outlier.txt
 
                  C 0  1024 1024  13 27 20.98    43 26 28.0
 
                  C 1    128  128  13 30 52.158    43 23 08.00
 
                  C 2    128  128  13 24 08.163    43 09 48.00
 
 
                In both cases the following images will be made:
 
                    M1_0.image, M1_1.image, M1_2.image    cleaned images
 
                    M1.0.model, M1_1.model, M1_2.model    model images
 
                    M1.0.residual, M1_1.residual, M1_2.residual    residual images
 
 
                 an outlier file more convenient.
 
                 an outlier file more convenient.
  
Line 523: Line 528:
 
                 then [45 66 123 124] is assigned to first field (imagename[0], or first line
 
                 then [45 66 123 124] is assigned to first field (imagename[0], or first line
 
                 of outlierfile).
 
                 of outlierfile).
 
+
               
 +
 
</pre>
 
</pre>

Revision as of 12:21, 25 May 2010

Help on clean task:

Invert and deconvolve images with selected algorithm

       The clean task has many options:
 
        1)  Make 'dirty' image and 'dirty' beam (psf)
        2)  Multi-frequency-continuum images or spectral channel imaging
        3)  Full Stokes imaging
        4)  Mosaicking of several pointings
        5)  Multi-scale cleaning
        6)  Widefield cleaning
        7)  Interactive clean boxing
        8)  Use starting model (eg from single dish)
 
 
       vis -- Name of input visibility file
               default: none; example: vis='ngc5921.ms'
       imagename -- Pre-name of output images:
               default: none; example: imagename='m2'
               output images are:
                 m2.image; cleaned and restored image
                        With or without primary beam correction
                 m2.psf; point-spread function (dirty beam)
                 m2.flux;  relative sky sensitivity over field
                 m2.flux.pbcoverage;  relative pb coverage over field 
                                      (gets created only for ft='mosaic')
                 m2.model; image of clean components
                 m2.residual; image of residuals
                 m2.interactive.mask; image containing clean regions
               To include outlier fields: 
                 imagename=['n5921','outlier1','outlier2'] 
       outlierfile --- Text file name which contains image names, sizes, field
                       centers
       field -- Select fields to image or mosaic.  Use field id(s) or name(s).
                  ['go listobs' to obtain the list id's or names]
               default: ''= all fields
                 If field string is a non-negative integer, it is assumed to
                 be a field index otherwise, it is assumed to be a 
                 field name
                 field='0~2'; field ids 0,1,2
                 field='0,4,5~7'; field ids 0,4,5,6,7
                 field='3C286,3C295'; field named 3C286 and 3C295
                 field = '3,4C*'; field id 3, all names starting with 4C
       spw -- Select spectral window/channels
               NOTE: channels de-selected here will contain all zeros if
               selected by the parameter mode subparameters.    
               Channel selection behaves differently in clean (e.g. The multiple
               ranges are not supported yet).
               default: ''=all spectral windows and channels
                 spw='0~2,4'; spectral windows 0,1,2,4 (all channels)
                 spw='0:5~61'; spw 0, channels 5 to 61
                 spw='<2';   spectral windows less than 2 (i.e. 0,1)
                 spw='0,10,3:3~45'; spw 0,10 all channels, spw 3, 
                                    channels 3 to 45.
                 spw='0~2:2~6'; spw 0,1,2 with channels 2 through 6 in each.
                 
                             
       selectdata -- Other data selection parameters
               default: True

  >>> selectdata=True expandable parameters
               See help par.selectdata for more on these

               timerange  -- Select data based on time range:
                   default: '' (all); examples,
                   timerange = 'YYYY/MM/DD/hh:mm:ss~YYYY/MM/DD/hh:mm:ss'
                   Note: if YYYY/MM/DD is missing date defaults to first 
                         day in data set
                   timerange='09:14:0~09:54:0' picks 40 min on first day
                   timerange='25:00:00~27:30:00' picks 1 hr to 3 hr 
                             30min on NEXT day
                   timerange='09:44:00' pick data within one integration 
                             of time
                   timerange='>10:24:00' data after this time
               uvrange -- Select data within uvrange (default units meters)
                   default: '' (all); example:
                   uvrange='0~1000klambda'; uvrange from 0-1000 kilo-lambda
                   uvrange='>4klambda';uvranges greater than 4 kilo lambda
               antenna -- Select data based on antenna/baseline
                   default: '' (all)
                   If antenna string is a non-negative integer, it is 
                   assumed to be an antenna index, otherwise, it is
                   considered an antenna name.
                   antenna='5&6'; baseline between antenna index 5 and 
                                 index 6.
                   antenna='VA05&VA06'; baseline between VLA antenna 5 
                                       and 6.
                   antenna='5&6;7&8'; baselines 5-6 and 7-8
                   antenna='5'; all baselines with antenna index 5
                   antenna='05'; all baselines with antenna number 05 
                                (VLA old name)
                   antenna='5,6,9'; all baselines with antennas 5,6,9 
                                   index numbers
               scan -- Scan number range.
                   default: '' (all)
                   example: scan='1~5'
                   Check 'go listobs' to insure the scan numbers are in order.
       mode -- Frequency Specification:
               NOTE: Channels deselected with spw parameter will contain all
                     zeros. 
               See examples below.
               default: 'mfs'
                 mode = 'mfs' means produce one image from all 
                      specified data.
                 mode = 'channel'; Use with nchan, start, width to specify
                        output image cube. 
                 mode = 'velocity', channels are specified in velocity.
                 mode = 'frequency', channels are specified in frequency.

  >>> mode='mfs' expandable parameters 
               Make a continuum image from the selected frequency
               channels/range using Multi-frequency synthesis
               algorithm for wide-band narrow field imaging.  nterms
               is the number of Taylor terms to be used to model the
               frequency dependence of the sky emission.  nterms=1 is
               equivalent to assuming no frequency dependence.
               nterms=2 is equivalent to the Sault-Wieringa algorithm
               (AandAS, 1994) reffreq is the reference frequency about
               which the Taylor expansion is done. ** Note that the 
               software implementation of the algorithm for nterms>1 
               is still experimental and will be fully available in a 
               later release. **

  >>> mode='channel', 'velocity', and 'frequency' expandable parameters
               nchan -- Total number of channels in the output image.
                 Example: nchan=100. 
                 Default: -1; Automatically selects enough channels to cover 
                 data selected by 'spw' and consistent with 'start' and 'width'. 
                 It is often easiest to leave nchan at the default value. 
               start -- First channel, velocity, or frequency. 
                 For mode='channel'; This selects the channel index number 
                 from the MS (0 based) that you want to correspond to the first 
                 channel of the output cube. The output cube will be in frequency 
                 space with the first channel having the frequency of the
                 MS channel selected by start.  start=0 refers to the first 
                 channel in the first selected spw, even if that channel 
                 is de-selected in the spw parameter. Channels de-selected by 
                 the spw parameter will be filled with zeros if included by
                 the start parameter. For example, spw=3~8:3~100 and start=2
                 will produce a cube that starts on the third channel (recall 0
                 based) of spw index 3, and the first channel will be blank.
                 example:start=5
                 For mode='velocity' or 'frequency': default=''; 
                 starts at first input channel of first input spw
                 examples: start='5.0km/s', or start='22.3GHz'.
               width -- Output channel width
                 For mode='channel', default=1; >1 indicates channel averaging
                 example: width=4.
                 For mode=' 'velocity' or 'frequency', default=''; width of
                 first input channel, or more precisely, the difference 
                 in frequencies between the first two selected channels. 
                 (for example if channels 1 and 3 are selected with spw, 
                  then the default width will be the difference between their
                  frequencies, and not the width of channel 1)
                 When not using the default, one must give units
                 examples: width='1.0km/s', or width='24.2kHz'.
                 Setting width>0 gives channels of increasing frequency for 
                 mode='frequency', and increasing velocity for mode='velocity'. 
               interpolation -- Interpolation type for spectral gridding onto 
                 the uv-plane. Options: 'nearest', 'linear', or 'cubic'.
                 default = 'linear'
               chaniter -- specify how spectral CLEAN is performed, 
                 default: chaniter=False;
                 example: chaniter=True; step through channels 
                  WARNING: The interactive clean with chaniter=True for
                    optical velocity mode
                    (mode='velocity' and veltype='optical') is
                    NOT YET IMPLEMENTED.
               outframe -- For mode='velocity', 'frequency', or 'channel':  velocity
                 reference frame of output image
                 Options: '','LSRK','LSRD','BARY','GEO','TOPO','GALACTO',
                          'LGROUP','CMB'
                 default: ''; same as input data
                 example: frame='bary' for Barycentric frame 
               veltype -- for mode='velocity' gives the velocity definition
                 Options: 'radio','optical' 
                 default: 'radio'
                 NOTE: the viewer always defaults to displaying the 'radio'
                   frame, but that can be changed in the position tracking
                   pull down.
           mode='mfs' examples:
               spw = '0,1'; mode = 'mfs'
                  will produce one image made from all channels in spw 
                       0 and 1
               spw='0:5~28^2'; mode = 'mfs'
                  will produce one image made with channels 
                       (5,7,9,...,25,27)

           mode='channel' examples:
               spw = '0'; mode = 'channel': nchan=3; start=5; width=4
                  will produce an image with 3 output planes
                  plane 1 contains data from channels (5+6+7+8)
                  plane 2 contains data from channels (9+10+11+12)
                  plane 3 contains data from channels (13+14+15+16)
               spw = '0:0~63^3'; mode='channel'; nchan=21; start = 0; 
                   width = 1
                  will produce an image with 20 output planes
                  Plane 1 contains data from channel 0
                  Plane 2 contains date from channel 2
                  Plane 21 contains data from channel 61
               spw = '0:0~40^2'; mode = 'channel'; nchan = 3; start = 
                   5; width = 4
                  will produce an image with three output planes
                  plane 1 contains channels (5,7)
                  plane 2 contains channels (13,15)
                  plane 3 contains channels (21,23)

       psfmode -- method of PSF calculation to use during minor cycles:
               default: 'clark': Options: 'clark','clarkstokes', 'hogbom'
               'clark'  use smaller beam (faster, usually good enough);
                for stokes images clean components peaks are searched
               in the I^2+Q^2+U^2+V^2 domain 
               'clarkstokes' locate clean components independently in
               each stokes image
               'hogbom' full-width of image (slower, better for poor 
               uv-coverage)
               Note:  psfmode will also be used to clean if imagermode = ''
       imagermode -- Advanced imaging e.g. mosaic or Cotton-Schwab clean
               default: imagermode='': Options: '', 'csclean', 'mosaic'
               default ''  => psfmode cleaning algorithm used

  >>> gridmode='' expandable parameters
               The default value of '' has no effect.
        
  >>> gridmode='widefield' expandable parameters
               Apply corrections for non-coplanar effects during imaging
               using the W-Projection algorithm (Cornwell et al. IEEE JSTSP
               (2008)) or faceting or a combination of the two.

               wprojplanes is the number of pre-computed w-planes used for
                   the W-Projection algorithm.  wprojplanes=1 disables
                   correction for non-coplanar effects. 
               facets is the number of facets used.  W-Projection is done
                   for each facet.

  >>> gridmode='aprojection' expandable parameters
               Corrects for the (E)VLA polarization squint using the
               A-Projection algorithm (Bhatnagar et al., AandA (2008)).
               cfcache is the name of the directory to be used to cache the
                   convolution functions.  These functions can be reused 
                   again if the image parameters are unchanged.  If the image 
                   parameters change, a new cache must be created (or the
                   existing one removed). 
               painc (in degrees) is the Parallactic Angle increment used to
                   compute the convolution functions.

  >>> imagermode='mosaic' expandable parameter(s):
               Make a mosaic of the different pointings (uses csclean style
               too)
               mosweight -- Individually weight the fields of the mosaic
                   default: False; example: mosweight=True
                   This can be useful if some of your fields are more
                   sensitive than others (i.e. due to time spent 
                   on-source); this parameter will give more weight to 
                   higher sensitivity fields in the overlap regions.
               ftmachine -- Gridding method for the mosaic;
                   Options: 'ft' (standard interferometric gridding), 'sd'
                   (standard single dish), 
                   and 'mosaic' (grid using PB as convolution function).
                   default: 'mosaic'; 
                   ONLY if imagermode='mosaic' is chosen and
                   ftmachine='mosaic', is heterogeneous imaging (CARMA, ALMA)
                   possible using the right convolution of primary beams for
                   each baseline.
               scaletype -- Controls scaling of pixels in the image plane.
                   (Not fully implemented...for now only controls 
                   what is seen if interactive=True...but in the future will 
                   control the image on which clean components are searched)
                   default='SAULT'; example: scaletype='PBCOR'
                   Options: 'PBCOR','SAULT'
                     'SAULT' when interactive=True shows the residual
                             with constant noise across the mosaic. 
                             be acheived by setting pbcor=True.
                     'PBCOR' uses the SAULT scaling scheme for
                             deconvolution, but if interactive=True shows the
                             primary beam corrected image during interactive. 

  >>> imagermode='csclean' expandable parameter(s): 
               Image using the Cotton-Schwab algorithm in between major cycles
               cyclefactor -- Change the threshold at which the deconvolution 
                   cycle will stop, degrid and subtract from the visibilities  
                   For poor PSFs, reconcile often (cyclefactor=4 or 5); 
                   For good PSFs, use cyclefactor 1.5 to 2.0. 
                   Note: threshold = cyclefactor * max sidelobe * max residual
                   default: 1.5; example: cyclefactor=4
               cyclespeedup -- Cycle threshold doubles in this number of 
                   iterations 
                   default: -1;
                   example: cyclespeedup=3
                   try cyclespeedup = 50 to speed up cleaning 

       multiscale -- set of scales to use in deconvolution.  If set,
               cleans with several resolutions using hobgom clean. The
               scale sizes are in units of cellsize.  So if
               cell='2arcsec', a multiscale scale=10 = 20arcsec.  First
               scale should always be 0 (point), we suggest second on
               the order of synthesized beam, third 3-5 times
               synthesized beam, etc. For example if synthesized beam
               is 10" and cell=2", try multscale = [0,5,15]. Note,
               multiscale is currently a bit slow.
               default: multiscale=[] (standard CLEAN with psfmode algorithm,
               no multi-scale). Example:  multiscale = [0,5,15] 

  >>> multiscale expandable parameter(s): 
               negcomponent -- Stop component search when the largest scale
                 has found this number of negative components;
                 -1 means continue component search even if the largest
                 component is negative.  default: -1; example: negcomponent=50
               smallscalebias -- A bias toward smaller scales. 
                   The peak flux found at each scale is weighted by 
                   a factor = 1 - smallscalebias*scale/max_scale, so
                   that Fw = F*factor.
                   Typically the values range from 0.2 to 1.0.
                   default: 0.6

       imsize -- Image pixel size (x,y).  DOES NOT HAVE TO BE A POWER OF 2
               default = [256,256]; example: imsize=[350,350]
               imsize = 500 is equivalent to [500,500]
               If include outlier fields, e.g., [[400,400],[100,100]] or
               use outlierfile.
               Avoid odd-numbered imsize.
       cell -- Cell size (x,y)
               default= '1.0arcsec';
               example: cell=['0.5arcsec,'0.5arcsec'] or
               cell=['1arcmin', '1arcmin']
               cell = '1arcsec' is equivalent to ['1arcsec','1arcsec']
               NOTE:cell = 2.0 => ['2arcsec', '2arcsec']
       phasecenter -- direction measure  or fieldid for the mosaic center
               default: '' => first field selected ; example: phasecenter=6
               or phasecenter='J2000 19h30m00 -40d00m00'
               If include outlier fields, 
                e.g. ['J2000 19h30m00 -40d00m00',J2000 19h25m00 -38d40m00']
               or use outlierfile.
       restfreq -- Specify rest frequency to use for output image
               default='' Occasionally it is necessary to set this (for
               example some VLA spectral line data).  For example for
               NH_3 (1,1) put restfreq='23.694496GHz'
       stokes -- Stokes parameters to image
               default='I'; example: stokes='IQUV';
               Options: 'I','IV''QU','IQUV','RR','LL','XX','YY','RRLL','XXYY'
       niter -- Maximum number iterations,
               if niter=0, then no CLEANing is done ("invert" only)
               default: 500; example: niter=5000
       gain -- Loop gain for CLEANing
               default: 0.1; example: gain=0.5
       threshold -- Flux level at which to stop CLEANing
               default: '0.0mJy'; 
               example: threshold='2.3mJy'  (always include units)
                        threshold = '0.0023Jy'
                        threshold = '0.0023Jy/beam' (okay also)
       interactive -- use interactive clean (with GUI viewer)
               default: interactive=False
               example: interactive=True
               interactive clean allows the user to build the cleaning
               mask interactively using the viewer.  The viewer will
               appear every npercycle interation, but modify as needed
               The final interactive mask is saved in the file
               imagename_interactive.mask.  The initial masks use the
               union of mask and cleanbox (see below).

  >>> interactive=True expandable parameters
               npercycle -- this is the  number of iterations between each
                 interactive update of the mask.  It is important to modify
                 this number interactively during the cleaning, starting with
                 a low number like 20, but then increasing as more extended
                 emission is encountered.

       mask -- Specification of cleanbox(es), mask image(s), and/or
               region(s) to be used for CLEANing. As long as the image has
               the same shape (size), mask images from a previous
               interactive session can be used for a new execution. NOTE:
               the initial clean mask actually used is the union of what
               is specified in mask and <imagename>.mask default: [] (no
               masking); Possible specification types: (a) Explicit
               cleanbox pixel ranges example: mask=[110,110,150,145] clean
               region with blc=110,100; trc=150,145 (pixel values) (b)
               Filename with cleanbox pixel values with ascii format:
               example: mask='mycleanbox.txt' <fieldid blc-x blc-y
               trc-x trc-y> on each line 
               1 45 66 123 124 
               2 23 100 300 340
               (c) Filename for image mask example: mask='myimage.mask'
               (d) Filename for region specification (e.g. from viewer)
               example: mask='myregion.rgn' (e) Combinations of any of the
               above example: mask=[[110,110,150,145],'mycleanbox.txt',
                                    'myimage.mask','myregion.rgn']
               If include outlier fields, then mask need to be specified in
               nested lists: 
                 e.g. mask=[[[110,110,150,145],'myimage.mask'],[],[20,20,40,40]]
               (A clean box with [110,110,150,145] and a image mask for main
                field, no mask for 1st outlier field, 1 clean box for second
                outlier field.)
       uvtaper -- Apply additional uv tapering of the visibilities.
               default: uvtaper=False; example: uvtaper=True
  >>> uvtaper=True expandable parameters
               outertaper -- uv-taper on outer baselines in uv-plane
                   [bmaj, bmin, bpa] taper Gaussian scale in uv or 
                   angular units. NOTE: the on-sky FWHM in arcsec is roughly
                   the uv taper/200 (klambda).
                   default: outertaper=[]; no outer taper applied
                   example: outertaper=['5klambda']  circular taper 
                                FWHM=5 kilo-lambda
                            outertaper=['5klambda','3klambda','45.0deg']
                            outertaper=['10arcsec'] on-sky FWHM 10 arcseconds
                            outertaper=['300.0'] default units are meters 
                                in aperture plane
               innertaper -- uv-taper in center of uv-plane
                   [bmaj,bmin,bpa] Gaussian scale at which taper falls to 
                   zero at uv=0
                   default: innertaper=[]; no inner taper applied
                   NOT YET IMPLEMENTED                
       modelimage -- Name of model image(s) to initialize cleaning. If
               multiple images, then these will be added together to
               form initial staring model NOTE: these are in addition
               to any initial model in the <imagename>.model image file
               default: '' (none); example: modelimage='orion.model'
               modelimage=['orion.model','sdorion.image'] Note: if the
               units in the image are Jy/beam as in a single-dish
               image, then it will be converted to Jy/pixel as in a
               model image, using the restoring beam in the image
               header
       weighting -- Weighting to apply to visibilities:
               default='natural'; example: weighting='uniform';
               Options: 'natural','uniform','briggs', 
                       'superuniform','briggsabs','radial'

  >>> Weighting expandable parameters
               For weighting='briggs' and 'briggsabs'
                   robust -- Brigg's robustness parameter
                   default=0.0; example: robust=0.5;
                   Options: -2.0 to 2.0; -2 (uniform)/+2 (natural)
               For weighting='briggsabs'
                   noise   -- noise parameter to use for Briggs "abs" 
                   weighting
                   example noise='1.0mJy'
               npixels -- uv-cell area used for weight calculation
                   example npixels=1
                   Default = 0
                   superuniform:  0 Means 3x3 cells for weighting
                     the cell weight is proportional to the weight of
                     the 3x3 cells centered on it.
                   superuniform = F means 1x1 cell for averaging weights.
                   briggs/briggsabs: 0 is similar to 1x1 cell weight.
                     1 may? be similar to 3X3 cells.
                   Only npixels 0 or 1 recommended
                   
       restoringbeam -- Output Gaussian restoring beam for CLEAN image
               [bmaj, bmin, bpa] elliptical Gaussian restoring beam
               default units are in arc-seconds for bmaj,bmin, degrees
               for bpa default: restoringbeam=[]; Use PSF calculated
               from dirty beam. 
               example: restoringbeam=['10arcsec'] circular Gaussian 
                        FWHM 10 arcseconds example:
                        restoringbeam=['10.0','5.0','45.0deg'] 10"x5" 
                        at 45 degrees
       pbcor -- Output primary beam-corrected image
                If pbcor=False, the final output image is NOT corrected for the 
                PB pattern (particularly important for mosaics), and therefore is
                not "flux correct". Correction can also be done after the 
                fact using immath to divide <imagename>.image by 
                the <imagename>.flux image. 
               default: pbcor=False; output un-corrected image 
               example: pbcor=True; output pb-corrected image (masked outside
                        minpb) 
       minpb -- Minimum PB level to use default=0.2;
               The flux image is used to determine this
               except for the case of mosaic with ftmachine='mosaic'
               where the flux.pbcoverage image is used.
               example: minpb=0.01 Note: this minpb is always in effect
                        (regardless of pbcor=True/False) 
       calready -- if True will create scratch columns if they are 
               not there. And after clean completes the predicted model 
               visibility is from the clean components are written to the ms.
       async -- Run asynchronously 
               default = False; do not run asychronously


        ======================================================================

                             HINTS ON CLEAN WITH FLANKING FIELDS

              1. Decide if the images will be specified directly in the
                 inputs or with an outlier file.  For more than a few fields,
                 an outlier file more convenient.

                Direct Method:

                   cell = ['1.0arcsec', '1.0arcsec']
                   imagename = ['M1_0','M1_1','M1_2]
                   imsize = [[1024,1024],[128,128],[128,128]]
                   phasecenter = ['J2000 13h27m20.98 43d26m28.0',
                             'J2000 13h30m52.159 43d23m08.02', 'J2000 13h24m08.16 43d09m48.0']

                 Text file method  (in outlier.txt)

                   imagename = 'M1'
                   outlierfile = 'outlier.txt'
                      [phasecenter, imsize ignored]

                   Contents of outlier.txt 
                   C 0   1024 1024   13 27 20.98     43 26 28.0
                   C 1    128  128   13 30 52.158    43 23 08.00
                   C 2    128  128   13 24 08.163    43 09 48.00

                In both cases the following images will be made:
                    M1_0.image, M1_1.image, M1_2.image     cleaned images
                    M1.0.model, M1_1.model, M1_2.model     model images
                    M1.0.residual, M1_1.residual, M1_2.residual     residual images

              2. Masks for flanking fields are specified in same way as 
                 in the single output field case, but need extra '[ ]' to
                 distinguish each field. 
                    mask=[['myregion.rg',[100,100,150,150]],['myimage1.mask'],[]]
                    would apply masks:
                    for the first field (main field),
                      myregion.rg and a box defined by [100,100,150,150] in pixels
                    for the seconf field (first outlier), myimage1.mask 
                    for the third field (second outlier), no mask (produce a mask for
                    whole field) 
                 However, if boxfiles are given, ids in the first column of the files
                 are used to match with fields (using order given imagename or
                 outlierfile. 
                 So, if the content of  a boxfile looks like this,
                         0 45 66 123 124 
                         1 23 100 300 340
                         2 20 20 40 40
                 then [45 66 123 124] is assigned to first field (imagename[0], or first line
                 of outlierfile).