applycal.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_applycal
def applycal(vis='', field='', spw='', intent='', selectdata=True, timerange='', uvrange='', antenna='', scan='', observation='', msselect='', gaintable=[''], gainfield=[''], interp=[''], spwmap=[], gaincurve=False, opacity=[], parang=False, calwt=True, applymode='', flagbackup=True):

        """Apply calibrations solutions(s) to data


       Applycal reads the specified gain calibration tables, applies
       them to the (raw) data column (with the specified selection),
       and writes the calibrated results into the corrected column.
       This is done in one step, so all available calibration tables must
       be specified.  Included parang, gaincurve, and opacity are used in
       obtaining previous calibration tables.

       Applycal will overwrite existing corrected data, and will flag data
       for which there is no calibration available.

       All calibration tables (both temporal, frequency, polarization
       calibrations) are specified in the gaintable parameter.  The
       calibration values associated with a restricted list of fields
       can also be selected for each table in gainfield.

       See task accum for instructions on forming calibration
       incrementally.  See task split for copying out any portion of the data
       and selected columns to a new visibility file.

       Keyword arguments:
       vis -- Name of input visibility file
               default: < none>; example: vis='ngc5921.ms'

      --- Data Selection: the data to which the calibration will be applied
        (see help par.selectdata for more detailed information)

      field -- Select field id(s) or field name(s) to apply calibration.
                 [run listobs to obtain the list id's or names]
               default: ''=all fields
               If field's string is an integer >=0, it is assumed to be an 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'; fields named 3C286 and 3C295
               field = '3,4C*'; field id 3, all names starting with 4C
      spw -- Select spectral window/channels 
               type 'help par.selection' for more examples.
             spw='0~2,4'; spectral windows 0,1,2,4 (all channels)
             spw='<2';  spectral windows less than 2 (i.e. 0,1)
             spw='0:5~61'; spw 0, channels 5 to 61, INCLUSIVE
             spw='*:5~61'; all spw with channels 5 to 62
             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
                       NOTE ';' to separate channel selections
             spw='0:0~10^2,1:20~30^5'; spw 0, channels 0,2,4,6,8,10,
                   spw 1, channels 20,25,30
       intent -- Select observing intent
                 default: ''  (no selection by intent)
                 intent='*BANDPASS*'  (selects data labelled with
                                       BANDPASS intent)
       selectdata -- Other data selection parameters
              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' 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~1000kl'; uvrange from 0-1000 kilo-lambda
              uvrange='>4kl';uvranges greater than 4 kilolambda
       antenna -- Select data based on antenna/baseline
              default: '' (all)
              If antenna's string is an integer >=0, it is taken to be an index
                otherwise, it is assumed to be 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'; baseline 5-6 and 7-8
              antenna='5'; all baselines with antenna index 5
              antenna='05'; all baselines with antenna name 05--vla antenna 5.
              antenna='5,6,10'; all baselines with antennas 5,6 and 10
       scan -- Scan number range
       observation -- Select by observation ID(s).
                       default: '' = all
                       example: '0~3,6'
       msselect -- Optional complex data selection (ignore for now)

       --- Calibration files to apply
       gaintable -- Gain calibration table(s) to apply 
               default: '' (none);
               examples: gaintable='ngc5921.gcal'
                   gaintable=['n5921.ampcal','n5921.phcal','n5921.bpass']
               All gain table types: 'G', GSPLINE, 'T', 'B', 'BPOLY', 'D's'
                   can be applied.
       gainfield -- Select a subset of calibrators from each gaintable
               default:'' ==> all sources in table;
               'nearest' ==> nearest (on sky) available field in table
               otherwise, same syntax as field
               example: gainfield='0~3'
                        gainfield=['0~3','4~6']  (for multiple gaintables)
       interp -- Interpolation type (in time[,freq]) to use for each gaintable.
                When frequency interpolation is relevant (B, Df, Xf),
                separate time-dependent and freq-dependent interp
                types with a comma (freq _after_ the comma).                
                Specifications for frequency are ignored when the
                calibration table has no channel-dependence.
                Time-dependent interp options ending in 'PD' enable a
                "phase delay" correction per spw for non-channel-dependent
                calibration types.
                default: '' --> 'linear,linear' for all gaintable(s)
                example: interp='nearest'   (in time, freq-dep will be
                                             linear, if relevant)
                         interp='linear,cubic'  (linear in time, cubic
                                                 in freq)
                         interp=',spline'  (spline in freq; linear in
                                            time by default)
                         interp=['nearest,spline','linear']  (for multiple gaintables)
                Options: Time: 'nearest', 'linear', 'nearestPD', 'linearPD'
                         Freq: 'nearest', 'linear', 'cubic', 'spline'
       spwmap -- Spectral windows combinations to form for gaintable(s)
               default: [] (apply solutions from each spw to that spw only)
               Example:  spwmap=[0,0,1,1] means apply the caltable solutions
                         from spw = 0 to the spw 0,1 and spw 1 to spw 2,3.
                         spwmap=[[0,0,1,1],[0,1,0,1]]  (for multiple gaintables)
                         
          Complicated example:

            gaintable=['tab1','tab2','tab3']
            gainfield='3C286'
            interp=['linear','nearest']
            spwmap=[[],[0,0,2]]
            
            This means: apply 3 cal tables, selecting only solutions for 3C286
            from tab1 (but all fields from tab2 and tab3, indicated by
            no gainfield entry for these files).  Linear interpolation
            (in time) will be used for 'tab1' and 'tab3' (default); 'tab2' will
            use nearest.  For the 'tab2', the calibration spws map
            will be mapped to the data spws according to 0->0, 0->1, 2->2.
            (I.e., for data spw=0 and 2, the spw mapping is one to one,
            but data spw 1 will be calibrated by solutions from spw 0.)  
           
       gaincurve -- Apply internal VLA/EVLA  antenna gain curve correction (True/False)
               default: False;
               Use gaincurve=True ONLY for VLA or EVLA data
       opacity -- Opacity correction to apply (nepers), per spw
               default: [] (no opacity correction for any spw)
               examples: 
                   A global value for all spws:
                     opacity=0.051 
                   Different values for spws 0,1,2:
                     opacity=[0.051, 0.055, 0.057] 
                   (if fewer opacity values than spws are specified,
                    then the last-specified value will be duplicated 
                    for all higher-numbered spws, e.g., in the above 
                    example, 0.057 will be used for spws 3 and higher, 
                    if they exist)
               Typical VLA values are: 5 GHz - 0.013, 8 GHz - 0.013
               15 GHz - 0.016, 23 GHz - 0.051, 43 GHz - 0.07
       parang -- If True, apply the parallactic angle correction.  FOR ANY
               POLARIZATION CALIBRATION AND IMAGING, parang = True
               default: False
       calwt -- Calibrate weights along with data for all
               relevant calibrations
               default: True; example: calwt=False
       applymode -- Calibration apply mode:
               ''='calflag' (default) calibrate data and apply flags from solutions
               'trial' report on flags from solutions, dataset entirely unchanged
               'flagonly' apply flags from solutions only, data not calibrated
               'calonly' calibrate data only (by unflagged solutions), flags from solutions NOT applied (use with extreme caution!)
       flagbackup -- Back up the state of the flags before applying calibration
                     default: True
       async -- Run task in a separate process 
                default: False; example: async=True



        """
        if type(gaintable)==str: gaintable=[gaintable]
        if type(gainfield)==str: gainfield=[gainfield]
        if type(interp)==str: interp=[interp]
        if type(spwmap)==int: spwmap=[spwmap]
        if type(opacity)==float: opacity=[opacity]

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

        mytmp['vis'] = vis
        mytmp['field'] = field
        mytmp['spw'] = spw
        mytmp['intent'] = intent
        mytmp['selectdata'] = selectdata
        mytmp['timerange'] = timerange
        mytmp['uvrange'] = uvrange
        mytmp['antenna'] = antenna
        mytmp['scan'] = scan
        mytmp['observation'] = observation
        mytmp['msselect'] = msselect
        mytmp['gaintable'] = gaintable
        mytmp['gainfield'] = gainfield
        mytmp['interp'] = interp
        mytmp['spwmap'] = spwmap
        mytmp['gaincurve'] = gaincurve
        mytmp['opacity'] = opacity
        mytmp['parang'] = parang
        mytmp['calwt'] = calwt
        mytmp['applymode'] = applymode
        mytmp['flagbackup'] = flagbackup
        pathname='file:///'+os.environ.get('CASAPATH').split()[0]+'/share/xml/'
        trec = casac.utils().torecord(pathname+'applycal.xml')

        casalog.origin('applycal')
        if trec.has_key('applycal') and casac.utils().verify(mytmp, trec['applycal']) :
            result = task_applycal.applycal(vis, field, spw, intent, selectdata, timerange, uvrange, antenna, scan, observation, msselect, gaintable, gainfield, interp, spwmap, gaincurve, opacity, parang, calwt, applymode, flagbackup)

        else :
          result = False
        return result