gaincal.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_gaincal
def gaincal(vis='', caltable='', field='', spw='', intent='', selectdata=True, timerange='', uvrange='', antenna='', scan='', observation='', msselect='', solint='inf', combine='', preavg=-1.0, refant='', minblperant=4, minsnr=3.0, solnorm=False, gaintype='G', smodel=[], calmode='ap', append=False, splinetime=3600.0, npointaver=3, phasewrap=180.0, gaintable=[''], gainfield=[''], interp=[''], spwmap=[], gaincurve=False, opacity=[], parang=False):

        """Determine temporal gains from calibrator observations

      The complex gains for each antenna/spwid are determined from the
      data column (raw data) divided by the model column.  The gains can
      be obtained for a specified solution interval, spw combination and
      field combination.  The GSPLINE spline (smooth) option is still under
      development.

      Previous calibrations (egs, bandpass, opacity, parallactic angle) can
      be applied on the fly.  At present with dual-polarized data, both
      polarizations must be unflagged for any solution to be obtained.

      Keyword arguments:
      vis -- Name of input visibility file
              default: none; example: vis='ngc5921.ms'
      caltable -- Name of output gain calibration table
              default: none; example: caltable='ngc5921.gcal'

      --- Data Selection (see help par.selectdata for more detailed information)

      field -- Select field using 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 a
                field index,  otherwise, it is assumed 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
          DON'T FORGET TO INCLUDE THE FLUX DENSITY CALIBRATOR IF YOU HAVE ONE
      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 61
             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: False 

              Must set selectdata=True to use the following selections:

      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 an
                antenna index, otherwise, it is assumed as 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 with indices 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,10'; all baselines with antennas 5,6,10 index numbers
      scan -- Scan number range.
              Check 'go listobs' to insure the scan numbers are in order.
      observation -- Observation ID(s).
                     default: '' = all
                     example: '0~2,4'
      msselect -- Optional complex data selection (ignore for now)

      --- Solution parameters
      gaintype -- Type of gain solution (G, T, or GSPLINE)
              default: 'G'; example: gaintype='GSPLINE'
              'G' means determine gains for each polarization and sp_wid
              'T' obtains one solution for both polarizations;  Hence. their
                phase offset must be first removed using a prior G.
              'GSPLINE' makes a spline fit to the calibrator data.  It is
                   useful for noisy data and fits a smooth curve through the
                   calibrated amplitude and phase.  However,
                   at present GSPLINE is somewhat experimental.  Use with
                   caution and check solutions.
              'K' solves for simple antenna-based single-band delays
                   via FFTs of the spectra on baselines to the
                   reference antenna.  (This is not global fringe-fitting.)
              'KCROSS' solves for a global cross-hand
                   delay.  Use parang=T and apply prior gain and
                   bandpass solutions.
      smodel -- Point source Stokes parameters for source model (experimental)
              default: [] (use MODEL_DATA column)
              example: [1,0,0,0] (I=1, unpolarized)
      calmode -- Type of solution
              default: 'ap' (amp and phase); example: calmode='p'
              Options: 'p','a','ap'
      solint --  Solution interval (units optional) 
              default: 'inf' (~infinite, up to boundaries controlled by combine); 
              Options: 'inf' (~infinite), 
                       'int' (per integration)
                       any float or integer value with or without units
              examples: solint='1min'; solint='60s'; solint=60 --> 1 minute
                        solint='0s'; solint=0; solint='int' --> per integration
                        solint-'-1s'; solint='inf' --> ~infinite, up to boundaries
                        interacts with combine
      combine -- Data axes to combine for solving
              default: '' --> solutions will break at scan, field, and spw
                      boundaries
              Options: '','scan','spw',field', or any comma-separated combination
              example: combine='scan,spw'  --> extend solutions over scan boundaries
                       (up to the solint), and combine spws for solving
      refant -- Reference antenna name(s); a prioritized list may be specified
              default: '' => no refant applied
              example: refant='4' (antenna with index 4)
                       refant='VA04' (VLA antenna #4)
                       refant='EA02,EA23,EA13' (EVLA antenna EA02, use
                                EA23 and EA13 as alternates if/when EA02
                                drops out)
              Use taskname=listobs for antenna listing
      minblperant --  Minimum number of baselines required per antenna for each solve
              default = 4
              Antennas with fewer baaselines are excluded from solutions.
              example: minblperant=10  => Antennas participating on 10 or more 
                       baselines are included in the solve
              minblperant = 1 will solve for all baseline pairs, even if only
                   one is present in the data set.  Unless closure errors are
                   expected, use taskname=gaincal rather than taskname=blcal to
                   obtain more options in data analysis.
      minsnr -- Reject solutions below this SNR
              default: 3.0 
      solnorm -- Normalize average solution amps to 1.0 after solution (G, T only)
              default: False (no normalization)
      append -- Append solutions to the (existing) table
              default: False; overwrite existing table or make new table
      splinetime -- Spline timescale (sec); used for gaintype='GSPLINE'
              default: 3600 (1 hour); example: splinetime=1000
              Typical splinetime should cover about 3 to 5 calibrator scans.
      npointaver -- Tune phase-unwrapping algorithm for gaintype='GSPLINE'
              default: 3; Keep at this value
      phasewrap -- Wrap the phase for changes larger than this amoun (degrees)
              default: 180; Keep at this value

      --- Other calibrations to apply on the fly before determining gaincal solution

      gaintable -- Gain calibration table(s) to apply 
               default: '' (none);
               examples: gaintable='ngc5921.gcal'
                         gaintable=['ngc5921.ampcal','ngc5921.phcal']
      gainfield -- Select a subset of calibrators from gaintable(s) to apply
               default:'' ==> all sources in table;
               'nearest' ==> nearest (on sky) available field in table
               otherwise, same syntax as field
               example: gainfield='0~2,5' means use fields 0,1,2,5 from gaintable
                        gainfield=['0~3','4~6'] means use field 0 through 3
                          from first gain file, field 4 through 6 for second.
      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'
                         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]]
      gaincurve -- Apply internal VLA antenna gain curve correction (True/False)
               default: False;
               Use gaincurve=True ONLY for VLA 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 more than 3 spws, spw 3 and higher will
                    be assigned the last specified value, or 0.057)
               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 (required
               for polarization calibration)
               default: False
      preavg -- Pre-averaging interval (sec)
              default=-1 (none).
               Rarely needed.  Will average data over periods shorter than
                 the solution interval first.
      async --  Run asynchronously
              default = False; do not run asychronously

        """
        if type(smodel)==float: smodel=[smodel]
        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['caltable'] = caltable
        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['solint'] = solint
        mytmp['combine'] = combine
        mytmp['preavg'] = preavg
        mytmp['refant'] = refant
        mytmp['minblperant'] = minblperant
        mytmp['minsnr'] = minsnr
        mytmp['solnorm'] = solnorm
        mytmp['gaintype'] = gaintype
        mytmp['smodel'] = smodel
        mytmp['calmode'] = calmode
        mytmp['append'] = append
        mytmp['splinetime'] = splinetime
        mytmp['npointaver'] = npointaver
        mytmp['phasewrap'] = phasewrap
        mytmp['gaintable'] = gaintable
        mytmp['gainfield'] = gainfield
        mytmp['interp'] = interp
        mytmp['spwmap'] = spwmap
        mytmp['gaincurve'] = gaincurve
        mytmp['opacity'] = opacity
        mytmp['parang'] = parang
        pathname='file:///'+os.environ.get('CASAPATH').split()[0]+'/share/xml/'
        trec = casac.utils().torecord(pathname+'gaincal.xml')

        casalog.origin('gaincal')
        if trec.has_key('gaincal') and casac.utils().verify(mytmp, trec['gaincal']) :
            result = task_gaincal.gaincal(vis, caltable, field, spw, intent, selectdata, timerange, uvrange, antenna, scan, observation, msselect, solint, combine, preavg, refant, minblperant, minsnr, solnorm, gaintype, smodel, calmode, append, splinetime, npointaver, phasewrap, gaintable, gainfield, interp, spwmap, gaincurve, opacity, parang)

        else :
          result = False
        return result