fluxscale.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_fluxscale
def fluxscale(vis='', caltable='', fluxtable='', reference=[''], transfer=[''], listfile='', append=False, refspwmap=[-1], incremental=False):

        """Bootstrap the flux density scale from standard calibrators

       After running gaincal on standard flux density calibrators (with or
       without an image model), and other calibrators with unknown flux
       densities (assumed 1 Jy), fluxscale applies the constraint that
       net system gain was, in fact, independent of field, on average,
       and that field-dependent gains in the input caltable are solely
       a result of the unknown flux densities for the calibrators.
       Using time-averaged gain amplitudes, the ratio between 
       each ordinary calibrator and the flux density calibrator(s) is 
       formed for each antenna and polarization (that they have in
       common).  For incremetal=False(default), the median of 
       this ratio over antennas and polarizations yields a correction 
       factor that is applied to the ordinary calibrators' gains. For 
       incremental=True, only the correction factors are written out 
       to the output fluxtable.

       The square of the gain correction factor for each calibrator
       and spw is the presumed flux density of that calibrator, and is
       reported in the logger.  The errors reported with this value
       reflect the scatter in gain ratio over antennas and
       polarizations, divided by the square root of the number of 
       antennas and polarizations available.  If the flux densities 
       for multiple spws exist, fitted spectral index and (for nspw>2)
       curvature are also reported. The MODEL_DATA column
       is currently _not_ revised to reflect the flux densities
       derived by fluxscale.  Use setjy to set the MODEL_DATA column,
       if necessary.

       The constant gain constraint is usually a reasonable assumption
       for the electronic systems on typical antennas.  It is
       important that external time- and/or elevation-dependent
       effects are separately accounted for when solving for the gain
       solution supplied to fluxscale, e.g., gain curves, 
       opacity, etc.  The fluxscale results can also be degraded
       by poor pointing during the observation.


       Keyword arguments:
       vis -- Name of input visibility file
               default: none; example: vis='ngc5921.ms'
       caltable -- Name of input calibration table
               default: none; example: caltable='ngc5921.gcal'
               This cal table was obtained from task gaincal.
       fluxtable -- Name of output, flux-scaled calibration table
               default: none; example: fluxtable='ngc5921.gcal2'
               The gains in this table have been adjusted by the
               derived flux density each calibrator.  The MODEL_DATA
               column has NOT been updated for the flux density of the
               calibrator.  Use setjy to do this if it is a point source.
       reference -- Reference field name(s)
               The names of the fields with a known flux densities or
                  visibilties that have been placed in the MODEL column
                  by setjy or ft for a model not in the CASA system.
               The syntax is similar to field.  Hence field index or
                  names can be used.
               default: none; example: reference='1328+307'
       transfer -- Transfer field name(s)
               The names of the fields with unknown flux densities.
                  These should be point-like calibrator sources
               The syntax is similar to field.  Hence source index or
                 names can be used.
               default: '' = all sources in caltable that are not specified
                  as reference sources.  Do not include unknown target sources
               example: transfer='1445+099, 3C84'; transfer = '0,4'

               NOTE: All fields in reference and transfer must have solutions
               in the caltable.

       listfile -- Fit listfile name
               The list file contains the flux density, flux density error,
                 S/N, and number of solutions (all antennas and feeds) for each
                 spectral window.  NOTE: The nominal spectral window frequencies
                 will be included in the future.
               default: '' = no fit listfile will be created.

       append -- Append fluxscaled solutions to the fluxtable.
               default: False; (will overwrite if already existing)
               example: append=True
       refspwmap -- Vector of spectral windows enablings scaling across
               spectral windows
               default: [-1]==> none.
               Example with 4 spectral windows:
               if the reference fields were observed only in spw=1 & 3,
               and the transfer fields were observed in all 4 spws (0,1,2,3),
               specify refspwmap=[1,1,3,3].
               This will ensure that transfer fields observed in spws 0,1,2,3
               will be referenced to reference field solutions only in
               spw 1 or 3.
      
       incremental -- Create an incremental caltable containing only gain correction 
               factors ( flux density= 1/(gain correction factor)**2)
               default: False; (older behavior = create flux-scaled gain table)
               example: incremental=True (output a caltable containing flux scale factors.)
              
               NOTE: If you use the incremental option, note that BOTH this incremental 
               fluxscale table AND an amplitude vs. time table should be supplied in applycal.

 
        """
        if type(reference)==str: reference=[reference]
        if type(transfer)==str: transfer=[transfer]
        if type(refspwmap)==int: refspwmap=[refspwmap]

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

        mytmp['vis'] = vis
        mytmp['caltable'] = caltable
        mytmp['fluxtable'] = fluxtable
        mytmp['reference'] = reference
        mytmp['transfer'] = transfer
        mytmp['listfile'] = listfile
        mytmp['append'] = append
        mytmp['refspwmap'] = refspwmap
        mytmp['incremental'] = incremental
        pathname='file:///'+os.environ.get('CASAPATH').split()[0]+'/share/xml/'
        trec = casac.utils().torecord(pathname+'fluxscale.xml')

        casalog.origin('fluxscale')
        if trec.has_key('fluxscale') and casac.utils().verify(mytmp, trec['fluxscale']) :
            result = task_fluxscale.fluxscale(vis, caltable, fluxtable, reference, transfer, listfile, append, refspwmap, incremental)

        else :
          result = False
        return result