peel_cli.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 casac
import string
import time
import inspect
import gc
import numpy
from odict import odict
from taskmanager import tm
from task_peel import peel
class peel_cli_:
    __name__ = "peel"
    __async__ = {}
    rkey = None
    i_am_a_casapy_task = None
    # The existence of the i_am_a_casapy_task attribute allows help()
    # (and other) to treat casapy tasks as a special case.

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

       self.parameters={'vis':None, 'dirs':None, 'remove':None, 'calmode':None,  'async':None}


    def result(self, key=None):
            #### here we will scan the task-ids in __async__
            #### and add any that have completed...
            if key is not None and self.__async__.has_key(key) and self.__async__[key] is not None:
               ret = tm.retrieve(self.__async__[key])
               if ret['state'] == "done" :
                  self.__async__[key] = None
               elif ret['state'] == 'crashed' :
                  self.__async__[key] = None
               return ret
            return None


    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")

        """
        if not hasattr(self, "__globals__") or self.__globals__ == None :
           self.__globals__=sys._getframe(len(inspect.stack())-1).f_globals
        #casac = self.__globals__['casac']
        casalog = self.__globals__['casalog']
        #casalog = casac.casac.logsink()
        self.__globals__['__last_task'] = 'peel'
        self.__globals__['taskname'] = 'peel'
        ###
        self.__globals__['update_params'](func=self.__globals__['taskname'],printtext=False,ipython_globals=self.__globals__)
        ###
        ###
        #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

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

        else :
            async = self.parameters['async']
            myparams['vis'] = vis = self.parameters['vis']
            myparams['dirs'] = dirs = self.parameters['dirs']
            myparams['remove'] = remove = self.parameters['remove']
            myparams['calmode'] = calmode = self.parameters['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.casac.utils().torecord(pathname+'peel.xml')

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

          casac.casac.utils().verify(mytmp, trec['peel'], True)
          scriptstr=['']
          saveinputs = self.__globals__['saveinputs']
          saveinputs('peel', 'peel.last', myparams, self.__globals__,scriptstr=scriptstr)
          if async :
            count = 0
            keybase =  time.strftime("%y%m%d.%H%M%S")
            key = keybase + "_" + str(count)
            while self.__async__.has_key(key) :
               count += 1
               key = keybase + "_" + str(count)
            result = tm.execute('peel', vis, dirs, remove, calmode)
            print "Use: "
            print "      tm.retrieve(return_value) # to retrieve the status"
            print 
            self.rkey = key
            self.__async__[key] = result
          else :
              tname = 'peel'
              spaces = ' '*(18-len(tname))
              casalog.post('\n##########################################'+
                           '\n##### Begin Task: ' + tname + spaces + ' #####')
              casalog.post(scriptstr[1][1:]+'\n', 'INFO')
              result = peel(vis, dirs, remove, calmode)
              casalog.post('##### End Task: ' + tname + '  ' + spaces + ' #####'+
                           '\n##########################################')

        except Exception, instance:
          if(self.__globals__.has_key('__rethrow_casa_exceptions') and self.__globals__['__rethrow_casa_exceptions']) :
             raise
          else :
             #print '**** Error **** ',instance
             tname = 'peel'
             casalog.post('An error occurred running task '+tname+'.', 'ERROR')
             pass

        gc.collect()
        return result
#
#
#
    def paramgui(self, useGlobals=True, ipython_globals=None):
        """
        Opens a parameter GUI for this task.  If useGlobals is true, then any relevant global parameter settings are used.
        """
        import paramgui
        if not hasattr(self, "__globals__") or self.__globals__ == None :
           self.__globals__=sys._getframe(len(inspect.stack())-1).f_globals

        if useGlobals:
            if ipython_globals == None:
                myf=self.__globals__
            else:
                myf=ipython_globals

            paramgui.setGlobals(myf)
        else:
            paramgui.setGlobals({})

        paramgui.runTask('peel', myf['_ip'])
        paramgui.setGlobals({})

#
#
#
    def defaults(self, param=None, ipython_globals=None, paramvalue=None, subparam=None):
        if not hasattr(self, "__globals__") or self.__globals__ == None :
           self.__globals__=sys._getframe(len(inspect.stack())-1).f_globals
        if ipython_globals == None:
            myf=self.__globals__
        else:
            myf=ipython_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(paramvalue==None and subparam==None):
               if(a.has_key(param)):
                  return a[param]
               else:
                  return self.itsdefault(param)
            else:
               retval=a[param]
               if(type(a[param])==dict):
                  for k in range(len(a[param])):
                     valornotval='value'
                     if(a[param][k].has_key('notvalue')):
                        valornotval='notvalue'
                     if((a[param][k][valornotval])==paramvalue):
                        retval=a[param][k].copy()
                        retval.pop(valornotval)
                        if(subparam != None):
                           if(retval.has_key(subparam)):
                              retval=retval[subparam]
                           else:
                              retval=self.itsdefault(subparam)
                     else:
                        retval=self.itsdefault(subparam)
               return retval


#
#
    def check_params(self, param=None, value=None, ipython_globals=None):
      if ipython_globals == None:
          myf=self.__globals__
      else:
          myf=ipython_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'

        #a = sys._getframe(len(inspect.stack())-1).f_globals

        if a.has_key(paramname) :
              return a[paramname]
peel_cli = peel_cli_()