pclean.py

Go to the documentation of this file.

#
# This file was generated using xslt from its XML file
#
# Copyright 2009, Associated Universities Inc., Washington DC
#
import sys
import os
from  casac import *
import string
from taskinit import casalog
#from taskmanager import tm
import task_pclean
def pclean(vis='', imagename='', imsize=[256, 256], cell=['1.0arcsec', '1.0arcsec'], phasecenter='', stokes='I', mask='', field='', spw='', ftmachine='ft', alg='clark', scales=[0], cyclefactor=1.5, majorcycles=1, niter=500, gain=0.1, threshold='0.0Jy', weighting='natural', robust=0.0, npixels=0, mode='continuum', nterms=1, start=0, nchan=1, width=1, restfreq='', interactive=False, npercycle=100, wprojplanes=128, facets=1, overwrite=True, uvtaper=False, outertaper=[''], timerange='', uvrange='', antenna='', scan='', observation='', pbcor=False, minpb=0.2, clusterdef=''):

        """Invert and deconvolve images with parallel engines

        Keyword arguments:
        Invert and deconvolve images with parallel engines
        Form images from visibilities. Handles continuum and spectral line 
        cubes using module pcont and pcube respectively.
 
        vis -- Name of input visibility file
               default: none; example: vis='ngc5921.ms'    
    
        imagename -- Pre-name of output CASA image. (only the prefix)
               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.model; image of clean components
                 m2.mask; image containing clean regions, when interative=True

        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 imsize=[500, 500]
               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 cell=['1arcsec', '1arcsec']
               NOTE:cell=2.0 => cell=['2arcsec', '2arcsec']

        phasecenter -- direction measure  or fieldid for the mosaic center
               default: '' => first field selected; 
               example: phasecenter=6
                     or phasecenter='J2000 19h30m00 -40d00m00'
        
        mask -- mask image 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.
               Only an image mask is allowed at this stage. Text formats not allowed yet.

        field -- Select fields in MS.  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
               examples:
                 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
               examples:
                 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

        ftmachine -- Fourier Transform Engine (Gridding method)
               Options: 
                 'ft' (standard interferometric gridding), 
                 'sd' (standard single dish),
                 'mosaic' (grid using PB as convolution function).
                 'wproject' (wprojection gridder to correct for widefield 'w' term errors)
               default: 'ft'
 
        alg -- Deconvolution algorithm
               Options: 'clark', 'hogbom', 'multiscale'
               default: 'clark'

         cyclefactor -- Controls the threshhold at which the
                   deconvolution cycle will pause to degrid and subtract the
                   model from the visibilities (Cotton-Schwab (CS) major cycle).
                   With poor PSFs, reconcile often (cyclefactor=4 or 5) for
                   reliability. 
                   With good PSFs, use cyclefactor = 1.5 to 2.0 for speed. 
                   Note: threshold = cyclefactor * max sidelobe * max residual
                   default: 1.5; example: cyclefactor=4
                   cyclefactor=0 allows the user to control number of CS major cycle 
         >>>  majorcycles -- integer number of CS major cycles to do 
               default: 1; 
               example: majorcycles=10
    
        niter -- Maximum number iterations,
               if niter=0, then no CLEANing is done ("invert" only)
               default: 500; 
               example: niter=5000

        threshold -- Flux level (residual peak) at which to stop CLEANing
               default: '0.0mJy';
               example: 
                 threshold='2.3mJy'  (always include units)
                 threshold='0.0023Jy'
                 threshold='0.0023Jy/beam' (okay also)
    
        weighting -- Weighting to apply to visibilities:
               Options: 'natural','uniform','briggs', 
                        'superuniform','radial'
               default: 'natural'; 
               example: weighting='uniform';

        scales -- list of scales in pixel for multiscale clean 
               default: [0]
               example: scales=[0, 3, 10]

        mode -- type of image to be generated 
               Options: 'continuum', 'cube'
               default: 'continuum'
               example:
                 mode='cube'; Use with nchan, start, step to specify
                        output image cube.
               NOTE: mode='velocity' or 'channel' or 'frequency'
               are aliased to mode='cube' for backward compatibility 
               and comfort.

  >>> mode='cube' 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 'step'
              It is often easiest to leave nchan at the default value.
           start -- First channel, velocity, or frequency.
              if start is an integer pclean will assume it is the a channel index
              if start is in units of velocity or frequency it will take it as such
              
              If the user use the the ms channel as starting pclean will assign 
              the first channel of the image to the data channel frequency in LSRK 
              of the first 
              spw selected at the first time seen in the data and the direction of the 
              source selected. 
              If the data is not in the LSRK frame the user should be aware that the 
              data channel indicated may not fall on the first image channel as time goes.

              example:start=5
             start can be in units of frequency or velocity too
             When velocity units is used it is obvious then that it is referring to the line
             whose restfrequency is provided by the user or is default one for the source 
             in the MS/SOURCE table.
             examples: start='5.0km/s', or start='22.3GHz'.
           width -- Output channel width
              should be in the same units as start 
              default=1; >1 indicates channel averaging
              if start is an integer, width has to be an integer defining the image channel 
              width by the number of channels of first spectral window selected
              example: width=4.
              when start is in frequency or velocity units then the width has to be in the same units.  default=''; 
             
              examples: width='1.0km/s', or width='24.2kHz'.

           
        interactive -- Create a mask interactively or not.
              interactive clean allows the user to build the cleaning
              mask interactively using the viewer.  

              default: False; 
              example: interactive=True
                The viewer will open with the image displayed. Select the
                region for the mask and double click in the middle of it.

         >>> npercycle -- Number of iteration in between viewer interactions.
               default=100

        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 for pb-correction and pb-based masking.
                    default=0.2;
                    example: minpb=0.01 
               When ftmachine is *not* 'mosaic' :
                  minpb is applied to the flux image (sensitivity-weighted pb).
               When ftmachine='mosaic' :
                  minpb is applied to the flux.pbcoverage image 
 
        overwrite -- If False use existing model image of same name to continue clean 
               if True the imagename.model and other associated images are overwitten 
               if they exist
               default: True


         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
                   For multiple MS input, a list of timerange strings can be
                 used:
          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 number
               scan -- Scan number range.
                   default: '' (all)
                   example: scan='1~5
               observation -- Observation ID range.
                   default: '' (all)
                   example: observation='1~5'


        clusterdef -- Name of a file that contains the cluster definition.
                      NOTE: there is a chapter in the cookbook on how to 
                      define this file
                       If clusterdef='' (the default) then all the cores, if possible, 
                       of the machine on 
                       which casapy is run will be used.
                  
          Example of a cube imaging run:
          
          pclean(vis="ngc5921.ms.contsub",imagename="loulou",imsize=[2500, 2500],
          cell=['15.0arcsec', '15.0arcsec'],phasecenter="",stokes="I",field="0",spw="*",
          ftmachine="ft",alg="hogbom",majorcycles=2, niter=6000,gain=0.1,
          threshold="8mJy",weighting="briggs",robust=0.5,npixels=0,mode="cube",
          start=5,nchan=46,width=1,interactive=True,overwrite=True,uvtaper=False,
          outertaper=[''],pbcor=True)              
                       
          Example of a continuum run:

          pclean(vis='sim100g_4chan15kRows.ms',
          imagename='hundredG_cont', imsize=[1500, 1500],
          cell=['0.135arcsec', '0.135arcsec'], mode='continuum', phasecenter='0',
          field='0', spw='*', ftmachine='wproject', wprojplanes=128,
          threshold='0.1mJy', 
          majorcycles=4, niter=10000, alg='clark',
          weighting='natural',
          overwrite=True)

 
        """
        if type(imsize)==int: imsize=[imsize]
        if type(cell)==float: cell=[cell]
        if type(scales)==int: scales=[scales]
        if type(outertaper)==str: outertaper=[outertaper]

#
#    The following is work around to avoid a bug with current python translation
#
        mytmp = {}

        mytmp['vis'] = vis
        mytmp['imagename'] = imagename
        mytmp['imsize'] = imsize
        if type(cell) == str :
           mytmp['cell'] = casac.quanta().quantity(cell)
        else :
           mytmp['cell'] = cell
        mytmp['phasecenter'] = phasecenter
        mytmp['stokes'] = stokes
        mytmp['mask'] = mask
        mytmp['field'] = field
        mytmp['spw'] = spw
        mytmp['ftmachine'] = ftmachine
        mytmp['alg'] = alg
        mytmp['scales'] = scales
        mytmp['cyclefactor'] = cyclefactor
        mytmp['majorcycles'] = majorcycles
        mytmp['niter'] = niter
        mytmp['gain'] = gain
        mytmp['threshold'] = threshold
        mytmp['weighting'] = weighting
        mytmp['robust'] = robust
        mytmp['npixels'] = npixels
        mytmp['mode'] = mode
        mytmp['nterms'] = nterms
        mytmp['start'] = start
        mytmp['nchan'] = nchan
        mytmp['width'] = width
        mytmp['restfreq'] = restfreq
        mytmp['interactive'] = interactive
        mytmp['npercycle'] = npercycle
        mytmp['wprojplanes'] = wprojplanes
        mytmp['facets'] = facets
        mytmp['overwrite'] = overwrite
        mytmp['uvtaper'] = uvtaper
        mytmp['outertaper'] = outertaper
        mytmp['timerange'] = timerange
        mytmp['uvrange'] = uvrange
        mytmp['antenna'] = antenna
        mytmp['scan'] = scan
        mytmp['observation'] = observation
        mytmp['pbcor'] = pbcor
        mytmp['minpb'] = minpb
        mytmp['clusterdef'] = clusterdef
        pathname='file:///'+os.environ.get('CASAPATH').split()[0]+'/share/xml/'
        trec = casac.utils().torecord(pathname+'pclean.xml')

        casalog.origin('pclean')
        if trec.has_key('pclean') and casac.utils().verify(mytmp, trec['pclean']) :
            result = task_pclean.pclean(vis, imagename, imsize, cell, phasecenter, stokes, mask, field, spw, ftmachine, alg, scales, cyclefactor, majorcycles, niter, gain, threshold, weighting, robust, npixels, mode, nterms, start, nchan, width, restfreq, interactive, npercycle, wprojplanes, facets, overwrite, uvtaper, outertaper, timerange, uvrange, antenna, scan, observation, pbcor, minpb, clusterdef)

        else :
          result = False
        return result