peel_pg.py

Go to the documentation of this file.

#
# This file was generated using xslt from its XML file
#
# Copyright 2008, Associated Universities Inc., Washington DC
#
import sys
import os
from casac import *
import string
import time
import inspect
import gc
import numpy
from odict import odict
from task_peel import peel
from task_peel import casalog

class peel_pg_:
    __name__ = "peel"

    def __init__(self) :
       self.__bases__ = (peel_pg_,)
       self.__doc__ = self.__call__.__doc__


    def __call__(self, vis=None, dirs=None, remove=None, calmode=None, async=None):

        """Do direction dependent selfcal(s) and optionally remove annoying sources.
Unfortunately at some level gains are direction-dependent, typically
because of either deviations between the true antenna voltage patterns and
the models being used, and/or fluctuations in one layer or another of the
Earth's atmosphere.  Bright sources located in the edges of the primary
beam therefore corrupt images of the central portions of the primary beam
in two ways.  The most obvious way is by throwing a corrupted version of
the PSF across the image.  Since it is corrupted, it cannot be deconvolved
away without first correcting the gains.  The second problem is that a
bright source can dominate the solutions of "classical" selfcalibration,
essentially forcing it to solve the gains for the direction of the bright
source instead of the pointing center.

Solving for and removing the effects of direction-dependent gains is known
in various forms as "peeling", "modcal", or most prosaically,
direction-dependent selfcalibration.  This task attempts
direction-dependent selfcalibration in the requested list of directions,
and optionally removes the associated sources.

The usual risks of selfcalibration (imperfect model and possibly
insufficient constraints) are particularly severe for peeling.  Approach it
with trepidation and stop as soon as possible.  Peeling can ameliorate the
effects of heterogeneous arrays, but it is better to use the right antenna
voltage patterns a priori.

Do not peel unless necessary.

Still here?  All right...read carefully...

Your desire to peel probably stems from the center of your "science field"
being spoiled by the distorted PSFs of bright sources near the edge of the
primary beam.  The fact that their PSFs are interfering with your field of
interest means that your science sources are interfering with the sources
to be peeled!  Thus before doing any peeling you should remove a model of
your science field from the visibilities.  However, the model should not
include any artifacts from the sources to be peeled.  The easiest way to
produce such a model is to clean down to the threshhold of the brightest
artifacts.  peel does not (yet) do this for you!  You are also of course
responsible for returning the model of your science field to the
visibilities once you have finished peeling.  Obviously, if your science
sources are fainter than the artifacts, removing them and replacing them is
not necessary.

If more than one source must be peeled there is a chance (calculated using
Murphy's Law) that they are interfering with each other.  peel does not yet
simultaneously solve for the gains in more than direction, so interfering
sources must be approached by peeling the brightest source down to the
level of the brightest artifacts in its vicinity, and next peeling whatever
is currently causing the worst artifacts, continuing as necessary.

If the interactions are especially strong, the cycle will have to be
iterated, refining the model(s) along the way.  The convergence is often
safer and faster if the first iteration of the cycle only solves for the
phases, and leaves phase + amplitude selfcalibration to the final
iteration.

Any given run of peel is nearly guaranteed to reduce the artifacts from the
source being peeled, so it can be tempting to continue peeling until the
artifacts drop below the noise.  Resist that temptation!  The number of
fitted parameters accumulates with each peel, so repeated peels force the
image toward the originally assumed model.  Even if the total number of
fitted parameters remains much smaller than the number of visibilities, the
interactions between peeled sources and the central field take their toll
on the science field.  peel sees residual PSF sidelobes from the science
region as artifacts that must be minimized.  Whether removing some flux
from the science source(s) is a risk or a certainty, the number of peels
should be kept down.  Overpeeling becomes easier to spot with experience,
but the symptoms are strongly telescope-dependent.




Example:

# Start with a phase-only peel, and keep the source so it can be phase +
# amplitude peeled if necessary.
peel(vis='my.ms', calmode="p", remove=False)

# Examine the result with viewer.

# OK, do a phase + amplitude removal.
peel(vis='my.ms', calmode="pa")

        """
        a=inspect.stack()
        stacklevel=0
        for k in range(len(a)):
          if (string.find(a[k][1], 'ipython console') > 0) or (string.find(a[k][1], '<string>') >= 0):
                stacklevel=k
                break
        myf=sys._getframe(stacklevel).f_globals
        myf['__last_task'] = 'peel'
        myf['taskname'] = 'peel'
        ###
        myf['update_params'](func=myf['taskname'],printtext=False)
        ###
        ###
        #Handle globals or user over-ride of arguments
        #
        function_signature_defaults=dict(zip(self.__call__.func_code.co_varnames,self.__call__.func_defaults))
        useLocalDefaults = False

        for item in function_signature_defaults.iteritems():
                key,val = item
                keyVal = eval(key)
                if (keyVal == None):
                        #user hasn't set it - use global/default
                        pass
                else:
                        #user has set it - use over-ride
                        if (key != 'self') :
                           useLocalDefaults = True
                        #myf[key]=keyVal

        myparams = {}
        if useLocalDefaults :
           for item in function_signature_defaults.iteritems():
               key,val = item
               keyVal = eval(key)
               exec('myparams[key] = keyVal')
               if (keyVal == None):
                   exec('myparams[key] = '+ key + ' = self.itsdefault(key)')
                   keyVal = eval(key)
                   if(type(keyVal) == dict) :
                      exec('myparams[key] = ' + key + ' = keyVal[len(keyVal)-1][\'value\']')

        else :
            uselessvariable = None 
            myparams['vis'] = vis = myf['vis']
            myparams['dirs'] = dirs = myf['dirs']
            myparams['remove'] = remove = myf['remove']
            myparams['calmode'] = calmode = myf['calmode']


        result = None

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

        mytmp['vis'] = vis
        mytmp['dirs'] = dirs
        mytmp['remove'] = remove
        mytmp['calmode'] = calmode
        pathname='file:///'+os.environ.get('CASAPATH').split()[0]+'/share/xml/'
        trec = casac.utils().torecord(pathname+'peel.xml')

        casalog.origin('peel')
        if not trec.has_key('peel') or not casac.utils().verify(mytmp, trec['peel']) :
            return False


        try :
          casalog.post('')
          casalog.post('##########################################')
          casalog.post('##### Begin Task: peel           #####')
          casalog.post('')
          result = peel(vis, dirs, remove, calmode)
          casalog.post('')
          casalog.post('##### End Task: peel           #####')
          casalog.post('##########################################')


# saveinputs for individule engine has no use
# saveinputs should alos be removed from casa_in_py.py
#
#
#          saveinputs = myf['saveinputs']
#          saveinputs('peel', 'peel.last', myparams)
#
#
        except Exception, instance:
          #print '**** Error **** ',instance
          pass

        gc.collect()
        return result
#
#
##
#    def paramgui(self, useGlobals=True):
#        """
#        Opens a parameter GUI for this task.  If useGlobals is true, then any relevant global parameter settings are used.
#        """
#        import paramgui
#
#        a=inspect.stack()
#        stacklevel=0
#        for k in range(len(a)):
#          if (string.find(a[k][1], 'ipython console') > 0) or (string.find(a[k][1], '<string>') >= 0):
#            stacklevel=k
#            break
#        myf = sys._getframe(stacklevel).f_globals
#
#        if useGlobals:
#            paramgui.setGlobals(myf)
#        else:
#            paramgui.setGlobals({})
#
#        paramgui.runTask('peel', myf['_ip'])
#        paramgui.setGlobals({})
#
#
#
#
    def defaults(self, param=None):
        a=inspect.stack()
        stacklevel=0
        for k in range(len(a)):
          if (string.find(a[k][1], 'ipython console') > 0) or (string.find(a[k][1], '<string>') >= 0):
                stacklevel=k
                break
        myf=sys._getframe(stacklevel).f_globals
        a = odict()
        a['vis']  = ''
        a['dirs']  = ""
        a['remove']  = True
        a['calmode']  = 'p'

        a['async']=False

### This function sets the default values but also will return the list of
### parameters or the default value of a given parameter
        if(param == None):
                myf['__set_default_parameters'](a)
        elif(param == 'paramkeys'):
                return a.keys()
        else:
                if(a.has_key(param)):
                   #if(type(a[param]) == dict) :
                   #   return a[param][len(a[param])-1]['value']
                   #else :
                      return a[param]


#
#
    def check_params(self, param=None, value=None):
      a=inspect.stack() 
      stacklevel=0
      for k in range(len(a)):
        if (string.find(a[k][1], 'ipython console') > 0) or (string.find(a[k][1], '<string>') >= 0):
            stacklevel=k
            break
      myf=sys._getframe(stacklevel).f_globals

#      print 'param:', param, 'value:', value
      try :
         if str(type(value)) != "<type 'instance'>" :
            value0 = value
            value = myf['cu'].expandparam(param, value)
            matchtype = False
            if(type(value) == numpy.ndarray):
               if(type(value) == type(value0)):
                  myf[param] = value.tolist()
               else:
                  #print 'value:', value, 'value0:', value0
                  #print 'type(value):', type(value), 'type(value0):', type(value0)
                  myf[param] = value0
                  if type(value0) != list :
                     matchtype = True
            else :
               myf[param] = value
            value = myf['cu'].verifyparam({param:value})
            if matchtype:
               value = False
      except Exception, instance:
         #ignore the exception and just return it unchecked
         myf[param] = value
      return value

#
#
    def description(self, key='peel', subkey=None):
        desc={'peel': 'Do direction dependent selfcal(s) and optionally remove annoying sources.',
               'vis': 'Name of the input visibility set.',
               'dirs': 'List of directions to peel.',
               'remove': 'Subtract the selfcalibrated source(s) from the data.',
               'calmode': 'Type of selfcal to do. (p: Phase only, a: Ampl only. ap: both',

               'async': 'If true the taskname must be started using peel(...)'
              }

        if(desc.has_key(key)) :
           return desc[key]

    def itsdefault(self, paramname) :
        a = {}
        a['vis']  = ''
        a['dirs']  = ""
        a['remove']  = True
        a['calmode']  = 'p'

        if a.has_key(paramname) :
              return a[paramname]
peel_pg = peel_pg_()