setjy.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_setjy
def setjy(vis='', field='', spw='', selectdata=False, timerange='', scan='', observation='', modimage='', listmodels=False, scalebychan=True, fluxdensity=-1, spix=0.0, reffreq='1GHz', standard='Perley-Butler 2010', useephemdir=False, usescratch=False):

        """Fills the model column with the visibilities of a calibrator

    The task sets the model visibility amp and phase of a specified source
    (generally a calibrator).  The simplest way is to enter the flux density
    (I,Q,U,V) explicitly, but this is valid only for a point source.

    For an extended source, the clean model (image.model) can be
    specified and the model visibilities associated with this clean
    model is placed in the visibility model column.

    Models are available for 3C48, 3C138, 3C286 between 1.4 and 43 GHz.
    3C147 is available above 4 GHz.  These models are scaled to the precise
    frequency of the data.  Only I models are presently available.

    The location of the models is system dependent: At the AOC and CV, the
    models are in the directory::/usr/lib/casapy/data/nrao/VLA/CalModels or
    /usr/lib64/casapy/data/nrao/VLA/CalModels (depending on whether 32 or 64
    bit CASA was installed on the machine being used).  In general (using
    Python), the stock models should be in
    casa['dirs']['data'] + '/nrao/VLA/CalModels'
    setjy also looks for models in the current directory before trying
    casa['dirs']['data'] + '/nrao/VLA/CalModels'.

    setjy need only be run on the calibrator sources with a known flux
    density and/or model.

    
    Solar System Objects are supported via the 'Butler-JPL-Horizons 2012' 
    standard. This uses new brightness temperature models and a new flux
    calculation code that replace the 'Butler-JPL-Horizons 2010' standard.
    The older 'Butler-JPL-Horizons 2010' standard is still available
    for comparison. Users may want to use predictcomp task to see the differeces. 
    Currently they are modeled as uniform temperature disks based
    on their ephemerides at the time of observation (note that this may
    oversimply objects, in particular asteroids).  The object name is
    obtained from the 'field' parameter. Recognized objects are listed
    below, under 'standard'.

    Note that fluxdensity, modimage, and standard interact in a possibly
    confusing way!  Generally, if fluxdensity[0] (Stokes I) is <= 0, it
    will be ignored.  If it is < 0, standard (which has a default) will
    be used to calculate flux density as a function of frequency, even if
    modimage is specified.  If is is exactly 0 and modimage is given, the
    brightness of the model image will be used as is.  If fluxdensity([0])
    is > 0, it will be used.  The latter two options come at the price of
    disabling frequency scaling, i.e. the same fluxdensity will be used for
    all frequencies.

    Keyword arguments:
    vis -- Name of input visibility file
            default: none.  example: vis='ngc5921.ms'
    field -- Select field using field id(s) or field name(s).
           default: ''=all fields, but run setjy one field at a time.
              [run listobs to obtain the list id's or names of calibrators]
           If field is a non-negative integer, it is assumed to be a field
           index.  Otherwise, it is taken to be a field name (case sensitive
           - it must match the name as listed by listobs).
           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
    spw -- Spectral window selection string.
           default: '' = all spectral windows
           Note that setjy only selects by spectral window, and ignores
           channel selections.  Fine-grained control could be achieved using
           (and possibly constructing) a cube for modimage.

    selectdata -- Other parameters for selecting part(s) of the MS
                  to operate on.
                  (Currently all time-oriented and most likely only of
                   interest when using a Solar System object as a calibrator.)
                  default: False

  >>> selectdata=True expandable parameters
               See help par.selectdata for more on these.

               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
                   For multiple MS input, a list of timerange strings can be
                   used:
                   timerange=['09:14:0~09:54:0','>10:24:00']
                   timerange='09:14:0~09:54:0''; apply the same timerange for
                                                 all input MSes
               scan -- Scan number range.
                   default: '' (all)
                   example: scan='1~5'
                   For multiple MS input, a list of scan strings can be used:
                   scan=['0~100','10~200']
                   scan='0~100; scan ids 0-100 for all input MSes
                   Check 'go listobs' to insure the scan numbers are in order.
               observation -- Observation ID range.
                   default: '' (all)
                   example: observation='1~5'


    modimage -- Model image (I only) for setting the model visibilities.
           modimage can be a cube, and its channels do not have to exactly
           match those of vis.  It is recommended to use modimage for
           sources that are resolved by the observation, but the
           Butler-JPL-Horizons standard supplies a basic model of what
           several Solar System objects look like.  default: '': do not use
           a model image.
    
           Each field must be done separately when using a model image.  The
           flux density of the image will be scaled from the frequency in
           the model to that actually used (ignoring fluxdensity), unless
           fluxdensity >= 0 (or fluxdensity[0] >= 0).  If
           fluxdensity([0]) is 0.0, the image's flux density will be used.
           If fluxdensity([0]) > 0.0, it will be used (and spix and
           reffreq if modimage is not a cube).  Since the spectral index
           usually varies with direction, applying a single spectral index
           to a 2D modimage is typically not as good as using a cube.

           Both the amplitude and phase are calculated.  At the AOC or CV,
           the models are located in casa['dirs']['data']
           + '/nrao/VLA/CalModels/', e.g.
           /usr/lib/casapy/data/nrao/VLA/CalModels/3C286_L.im
                lib64

           If modimage does not start with '/', setjy will look for a match
           in '.', './CalModels', and any CalModels directories within
           the casa['dirs']['data'] tree (excluding certain branches).

           Note that modimage should be deconvolved, i.e. a set of clean
           components instead of an image that has been convolved with a
           clean beam.

    listmodels -- If True, do nothing but list candidates for modimage
           (for extragalactic calibrators) that are present on the system.  It looks for *.im* *.mod* in .,
           CalModels, and CalModels directories in the casa['dirs']['data']
           tree.  It does not check whether they are appropriate for the MS!
           If standard='Butler-JPL-Horizons 2012', Tb models (frequency-depended
           brightness temperature models) for Solar System objects used in the 
           standard.  For standard='Butler-JPL-Horizons 2010', the recognized
           Solar System objects are listed. 

    scalebychan -- This determines whether the fluxdensity set in the model is
            calculated on a per channel basis. If False then it only one
            fluxdensity value is calculated per spw.  (Either way, all channels
            in spw are modified.)  It is effectively True if fluxdensity[0] >
            0.0. 
            default: True

    fluxdensity -- Specified flux density [I,Q,U,V] in Jy
            default: -1, uses [1,0,0,0] flux density for unrecognized sources,
            and standard flux densities for ones recognized by 'standard',
            including 3C286, 3C48, 3C147, and several planets, moons, and
            asteroids.  setjy will try to use standard if fluxdensity is not
            positive.

            Only one flux density can be specified at a time.  The phases are
               set to zero.
            example   fluxdensity=-1  will use standard for recognized
                      calibrators (like 3C286, 3C147 and 3C48, depending on
                      standard) and insert 1.0 for selected fields with
                      unrecognized sources.
            example   field = '1'; fluxdensity=[3.2,0,0,0] wil put in 
                      a flux density of I=3.2 for field='1'

            At present (June 2000), this is the only method to insert a
            polarized flux density model.
            example:  fluxdensity=[2.63,0.21,-0.33,0.02]
                      will put in I,Q,U,V flux densities of 2.63,0.21,-0.33,
                      and 0.02, respectively, in the model column.

    spix -- Spectral index for fluxdensity:
                 S = fluxdensity * (freq/reffreq)**spix
            Default: 0 (no effect)
            Only used if fluxdensity is being used.
            N.B.: If fluxdensity is positive, and spix is nonzero, then reffreq
                  must be set too!  (See below)

                  It is applied in the same way to all polarizations, and does
                  not account for Faraday rotation or depolarization.

    reffreq -- The reference frequency for spix, given with units.
            Default: '1GHz'; this is only here to prevent division by 0!
            N.B.: If the flux density is being scaled by spectral index,
            then reffreq must be set to whatever reference frequency is
            correct for the given fluxdensity and spix.  It cannot be
            determined from vis.  On the other hand, if spix is 0, then any
            positive frequency can be used (and ignored).

            Examples: '86.0GHz', '4.65e9Hz'

    standard -- Flux density standard, used if fluxdensity[0] < 0.0
            default: 'Perley-Butler 2010'; example: standard='Baars'
            Options: 'Baars','Perley 90','Perley-Taylor 95',
               'Perley-Taylor 99', 'Perley-Butler 2010', 'Perley-Butler 2013',
               'Butler-JPL-Horizons 2010', and 'Butler-JPL-Horizons 2012'. 
            All but the last two are for extragalactic calibrators,
            and the final two are for Solar System objects.  

            Extragalactic calibrators:
            Following source names and their common aliases are recognized.
            The last column shows which standards support for each source.
            Note that the task does not do exact matching of the name and
            it recognizes as long as the field name  contains the string 
            listed below (e.g. 'PKS 1934-638' works). 
            -----------------------------------------------------------
            3C Name B1950 Name J2000 Name Alt. J2000 Name  standards*
            3C48    0134+329   0137+331   J0137+3309       1,3,4,5,6
            3C123   0433+295   0437+296   J0437+2940       2 
            3C138   0518+165   0521+166   J0521+1638       1,3,4,5,6
            3C147   0538+498   0542+498   J0542+4951       1,3,4,5,6
            3C196   0809+483   0813+482   J0813+4813       1,2 
            3C286   1328+307   1331+305   J1331+3030       1,2,3,4,5,6
            3C295   1409+524   1411+522   J1411+5212       1,2,3,4,5,6
              -     1934-638      -       J1939-6342       1,3,4,5,6
            ----------------------------------------------------------- 
            * supported in: 1 - Perley-Butler 2010, 2 - Perley-Butler 2013,
            3 - Perley-Taylor 99, 4 - Perley-Taylor 95, 5 - Perley 90, 6 - Baars 

            Solar system objects:
            The 'Butler-JPL-Horizons 2012' standard is recommended over 
            'Butler-JPL-Horizons 2010' as the former uses updated models.
            Recognized Solar System objects (for 'Butler-JPL-Horizons 2012') are: 
             
               
               Planets: Venus, Mars, Jupiter, Uranus, Neptune
               
               Moons: Jupiter: Io, Europa, Ganymede, Callisto
                   Saturn:  Titan 

               Asteroids: Ceres, Pallas**, Vesta**, Juno**

            * Venus: model for ~300MHz to 350GHz, no atmospheric lines (CO,H2O,HDO, etc)
            * Mars: tabulated as a function of time and frequency (30 - 1000GHz) based on 
               Rudy el tal (1988), no atmopheric lines (CO, H20, H2O2, HDO, etc)
            * Jupiter: model for 30-1020GHz, does not include synchrotron emission
            * Uranus: model for 60-1800GHz, contains no rings or synchrotron.
            * Neptune: model for 2-2000GHz, the broad CO absorption line
               is included, but contains no rings or syncrotron. 
            * Titan: model for 53.3-1024.1GHz, include many spectral lines

            **  not recommended (The temperature is not yet adjusted for
                varying distance from the Sun.  The model data can be scaled
                after running setjy, but it is an involved process.)

               The 'field' parameter must match the case of the field name(s)
               in vis (as shown by listobs).

            Flux density calculation with Solar System objects depends on
            ephemerides. The setjy task looks for the data in  
            
            os.getenv('CASAPATH').split()[0] + '/data/ephemerides/JPL-Horizons'.

            If no ephemeris for the right object at the right time is
            present, the calculation will fail.  Ask the helpdesk to make an
            ephemeris.  The very adventurous and well versed in python can
            try it using CASA's recipes.ephemerides package:
                 import recipes.ephemerides as eph
                 help eph

            CASA comes with ephemerides for several more objects, but they
            are intended for use with me.framecomet(), and are not (yet)
            suitable flux density calibrators.  It is up to the observer to
            pick a good flux density calibrator (bright, spherical and
            featureless, on a circular orbit, in the right part of the sky,
            and not too resolved).  Even some of the objects listed above
            may prove to require more sophisticated flux density models than
            are currently implemented in CASA.  For many objects running
            casalog.filter('INFO1') before running setjy will send more
            information to the logger.  The cookbook also has an appendix
            with descriptions of the models used by setjy (both
            extragalactic and Solar System).

       >>> standard="Butler-JPL-Horizons 2012" expandable parameter

            useephemdir -- If True: use the direction from the ephemeris table for 
                the solar system object. 
                default: False -use the direction information in the MS(i.e. Field table) 

        usescratch  -- If False: 'virtual' model is created. The model is saved in the header 
        and model visibilities are evaluated when calculating calibration or plotting in plotms.
        If True: the model visibility will be evaluated and saved on disk in the MODEL_DATA 
        column.  This will increase your ms in size by a factor of 1.5 (w.r.t. the case where 
        you only have the DATA and the CORRECTED_DATA column).  Use True if you need to interact 
        with the MODEL_DATA in python, say.

        *By running usescratch=T, it will remove the existing virtual model from previous runs.
        usescratch=F will not remove the existing MODEL_DATA but in subsequent process
        the virtual model with matching field and spw combination will be used if it exists
        regardless of the presence of the MODEL_DATA column.
         
        default: False        
            

        """

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

        mytmp['vis'] = vis
        mytmp['field'] = field
        mytmp['spw'] = spw
        mytmp['selectdata'] = selectdata
        mytmp['timerange'] = timerange
        mytmp['scan'] = scan
        mytmp['observation'] = observation
        mytmp['modimage'] = modimage
        mytmp['listmodels'] = listmodels
        mytmp['scalebychan'] = scalebychan
        mytmp['fluxdensity'] = fluxdensity
        mytmp['spix'] = spix
        mytmp['reffreq'] = reffreq
        mytmp['standard'] = standard
        mytmp['useephemdir'] = useephemdir
        mytmp['usescratch'] = usescratch
        pathname='file:///'+os.environ.get('CASAPATH').split()[0]+'/share/xml/'
        trec = casac.utils().torecord(pathname+'setjy.xml')

        casalog.origin('setjy')
        if trec.has_key('setjy') and casac.utils().verify(mytmp, trec['setjy']) :
            result = task_setjy.setjy(vis, field, spw, selectdata, timerange, scan, observation, modimage, listmodels, scalebychan, fluxdensity, spix, reffreq, standard, useephemdir, usescratch)

        else :
          result = False
        return result