Clean

From CASA Guides
Revision as of 09:44, 30 October 2009 by Jgallimo (talk | contribs) (Created page with 'Deconvolve an image with selected algorithm This is the main clean deconvolution task. It contains many functions 1) Make 'dirty' image and 'dirty' beam (psf)…')

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

Deconvolve an image with selected algorithm

      This is the main clean deconvolution task.  It contains many functions

       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)  Interactive clean boxing
       7)  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 in mosaic.  Use field id(s) or field 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: This selects the data passed as the INPUT to mode
              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.
                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
              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: 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.  See examples below
                mode = 'velocity', means channels are specified in 
                     velocity.
                mode = 'frequency', means 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.
 >>> mode expandable parameters (for modes other than 'mfs')
              Start, width are given in units of channels, frequency 
                 or velocity as indicated by mode (note: only nearest neighbour 
                 interpolation is available at this time).
              nchan -- Number of channels (planes) in output image
                default: 1; example: nchan=3
              start -- Start input channel (relative-0)
                default=0; example: start=5
              width -- Output channel width in units of the input
                    channel width (>1 indicates channel averaging)
                default=1; example: width=4
              interpolation -- Interpolation type of spectral data when gridded on
                 the uv-plane
                default = 'nearest'
                   HOWEVER, 'linear' is recommended
              outframe -- velocity reference frame of output image (for mode='velocity' or 'frequency')
                Options: ,'LSRK','LSRD','BARY','GEO','TOPO','GALACTO','LGROUP','CMB'
                default: ; same as input data; example: frame='bary' for Barycentric frame 
              veltype -- (for mode='velocity') velocity definition
                Options: 'radio','optical','true' (='relativistic')
                veltype='true' (or equivalently 'relativistic') 
                for velocity defined without approximations using the relativistic expression 
                default: 'radio'
          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)
              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 be used to clean is 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
              Correct 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):
              Image as 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 image;
                  Options: ft (standard interferometric gridding), sd
                  (standard single dish) both (ft and sd as appropriate),
                  mosaic (gridding use PB as convolution function)
                  default: 'mosaic'; example: ftmachine='ft'
                  if imagermode mosaic is chosen and ftmachine is mosaic, 
                  heterogenous arrays like Carma or Alma are recognized
                  and the right Primary Beam (depending on the size of the dish)
                  is used 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. If
                            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.
                    'PBCOR' uses the SAULT scaling scheme for
                            deconvolution, but if interactive=True shows the
                            primary beam corrected image; the final PBCOR
                            image is "flux correct" if pbcor=True.
 >>> 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 using 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','IVQU','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 clean
                  to update mask interactively.  It is important to modify
                  this number interactively during the cleaning, starting wiht
                  a low number like 20, but then increasing as more extended
                  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
              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: uv taper in (klambda) is roughly on-sky 
                  FWHM(arcsec/200)
                  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"
                           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" example:
                       restoringbeam=['10.0','5.0','45.0deg'] 10"x5" 
                       at 45 degrees
      pbcor -- Output primary beam-corrected image 
              default: pbcor=False; output un-corrected image 
              example: pbcor=True; output pb-corrected image (masked outside
                       minpb) Note: if you set pbcor=False, you can later
                       recover the pbcor image by dividing by the .flux image
                       (e.g. using immath)
      minpb -- Minimum PB level to use default=0.1;
              The flux image is used to determine this
              except for the case of mosaic with ft='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
                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).