The setjy task sets the model visibility amplitude and phase associated with a flux density scale and a specified clean components image into the model column of the MS data set. The flux density (I,Q,U,V) for a point source calibrator can be entered explicitly.  If no model is specified, then a point source at the phase center is assumed.  For sources that are recognized flux calibrators (listed in Flux Calibrator Models), setjy can calculate the flux densities as a function of frequency (and time, for some extragalactic sources classified as the variable sources and Solar System objects). Otherwise, the flux densities should be manually specified ( standard=’manual’).

Overview

The basic modes of operations are specified by the parameter, standard. As the name indicates, the bulk of its options are different flux density standards available in CASA as listed in Flux Calibrator Models. In addition, standard=’manual’ allows flux density scaling to be specified directly instead of using one for the flux density standards. And finally, standard=‘fluxscale’ allows the user to insert a flux density based on the python dictionary result from the fluxscale task, after the initial setjy on the primary flux calibrator, to insert proper flux density models for secondary calibrators in the MS.

By default the setjy task will cycle through all selected fields, spectral windows and channels, (one solution per spw with scalebychan = False) , setting the flux density either to 1 Jy (unpolarized), or if the source is recognized as one of the calibrators, to the flux density (assumed unpolarized) appropriate to the observing frequency.

Optionally, the MODEL_DATA column can be filled with the Fourier transform of the model image. But for any given MeasurementSet, the performance and data storage requirements are less demanding without the MODEL_DATA column. If usescratch=False, the model is stored as a 'virtual' model. The model parameters are saved either in the SOURCE_MODEL column in the SOURCE table (if one exists) or in the keyword
of the main table in the MS and model visibilities are evaluated on the fly when processing calibration or plotting in plotms.

The result containing flux densities for each spw is returned as a Python dictionary when it is executed as the function with arguments,

Manually setting Flux Densities: standard=‘manual’

With this mode, the flux densities and other relevant parameters necessary to describe the model can be entered manually. The following are the subparameters.

In the simplest version, the flux for Stokes I can be set via the fluxdensity subparameter as the first entry in a list. In the above example [1,0,0,0] setjy sets the flux to 1 Jy. Additional Stokes specifications can be set in remaining list members.  All fluxdensity vales must be given in units of Jy. A spectral index can be provided via the spix and reffreq subparameters. Finally it is also possible to provide coefficients for the polarization fraction and angle as well as a rotation measure to define the model (polindex, polangle, rotmeas subparameters).

The spix subparamter can accept a list of values to include the spectral index of Stokes I in higher order terms, using the definition of the flux density at a frequency, $\nu$, $S(\nu)=fluxdensity[0]*\frac{\nu}{reffreq}^{spix[0]+spix[1]*log(\nu/reffreq)+..}$ . The reffreq is given by a string including the unit (e.g. '10GHz', note that there is no space between the value and the unit). The polindex takes a list of coefficents ([p0, p1, p2...]) using the definition of frequency-dependent polarization index (PI) , where

$ PI = \frac{\sqrt{Q^2+U^2}}{I} = p0 + p1*\frac{\nu-reffreq}{reffreq} + p2*(\frac{\nu-reffreq}{reffreq})^2 + ... $.

Similarly, the polangle subparameter takes a list of coefficients ([a0,a1,a2, ..]) using the definition of polarization angle ($\chi$), where

$\chi = 0.5arctan\frac{U}{Q} = a0 + a1*\frac{\nu-reffreq}{reffreq} + a2*(\frac{freq-reffreq}{reffreq})^2 + .. $.

Using the Predefined Standards

For the VLA, the default source models are customarily point sources defined by the ’Baars’, ’Perley 90’, ’Perley-Taylor 99’, ’Perley-Butler 2010’, time-variable ’Perley-Butler 2013’,’Scaife-Heald 2012’, or ’Stevens-Reynolds 2016’ flux density scales (See Flux Calibrator Models for details; ’Perley-Butler 2013’ is the current standard by default), or point sources of unit flux density if the flux density is unknown.

Most calibrator sources are based on radio emission from quasars and jets. The spectral indices of these sources are such that at (sub)mm wavelengths the majority of these sources become too weak and variable to reliably set the flux density scale. Alternatives are thermal objects such as planets, moons, and asteroids. Being Solar System objects, these objects do not move at the sidereal rate and may be (strongly) resolved. The standard=’Butler-JPL-Horizons 2010’ and the recommended standard=’Butler-JPL-Horizons 2012’ (for more information on the implemented models, see Flux Calibrator Models page and also ALMA Memo 594  [1].) option of setjy includes flux density calibration using Solar System objects.

For ’Butler-JPL-Horizons 2012’ CASA currently supports the objects listed in Flux Calibrator Models to be applied to ALMA data. These names are recognized when they are used in the ’field’ parameter in setjy. In that case, setjy will obtain the geocentric distance and angular diameter at the time of the observation from a JPL–Horizons ephemeris and calculate model visibilities. Currently the objects are modeled as uniform temperature disks. Note that this model may oversimplify the real structure, in particular asteroids. The supported brightness temperature models for Solar System objects can be listed by selecting a standard and listmodels=True without setting any other parameters as shown below:

Each model contains temperatures at tabulated frequencies except for Mars. For Mars, the model temperatures are tabulated in time and frequency (see Flux Calibrator Models - Conventions, Data Formats for more details). 

Citation Number	1
Citation Text	Butler 2012, ALMA Memo #594

For selected asteroids, time variable models are available based on thermophysical modeling by T. Mueller (private communication) for January 1st, 2015 and beyond. Currently, the new models are available for Ceres, Pallas, and Vesta. A model is also available for Lutetia but using this source for ALMA absolute flux calibration is not advised. These new models are automatically chosen for the data taken after 2015 January 1, 0 hr UT. These models are also listed when the setjy task is executed with standard=‘Butler-JPL-Horizons 2012’ and listmodels=True. These model data files contain flux densities tabulated in time and frequency (see Flux Calibrator Models - Conventions, Data Formats for more details).  

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 ALMA helpdesk to make an ephemeris. The very adventurous and well versed in python can try it using CASA's recipes.ephemerides package:

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.  "Reference Material"  has section "Flux Calibrator Models" with descriptions of the models used by setjy (both extragalactic and Solar System).

Using Calibration Models for Resolved Sources

For observations of Solar System objects using the ’Butler-JPL-Horizons 2010’ and ’Butler-JPL-Horizons 2012’ models, setjy will know and apply the flux distribution across the extended structure of the calibrators.

For other sources, namely VLA calibrator sources, a flux density calibrator can be resolved at the observing frequency and the point source model generated by setjy will not be appropriate. If available, a model image of the resolved source at the observing frequency may be used to generate the appropriate visibilities using the model subparameter (currently only available for standard='Perley-Butler 2010' and standard='Perley-Butler 2013’).  To do this, the model subparameter must include the full path to the model image. If the model subparameter is given only the file name, setjy will first search for the model image in the current working directory.  

Also note that using setjy with a model image will only operate on that single source.  Therefore, for different sources, setjy would need to be run multiple times (with different field settings). The default model images available are listed by listmodel=True and are found in the .../data/nrao/VLA/CalModels sub-directory of the CASA installation.  Note the full path to the flux density calibrators may change depending on the installation directory or copies of these models can be placed in the current working directory.

Currently available model images are:

More calibrator models for the VLA are available at
 https://science.nrao.edu/facilities/vla/data-processing/models .These are all un-convolved images of AIPS CC lists. It is important that the model image not be one convolved with a finite beam; it must have units of Jy/pixel (not Jy/beam).

Note that setjy will rescale the flux in the models for known sources to match those it would have calculated. It will thus extrapolate the flux out of the frequency band of the model image to whatever spectral windows in the MS is specified (but will use the structure of the source in the model image).

If no source model is available, the uvrange selection may be needed during calibration to exclude the baselines where the resolution effect is significant. There is no hard and fast rule for this, though should be considered if the calibrator shows a drop of more than 10% on the longest baselines (use plotms to look at this). The antenna selection may also be needed if the calibrator is heavily resolved and there are few good baselines to the outer antennas. Note that uvrange may also be needed to exclude the short baselines on some calibrators that have extended flux not accounted for in the model.

Note: For the following models, hard-coded radius limits on the model images are applied automatically.

3C286	3.0"
3C48	0.95"
3C147	0.85"
3C138	0.75"

Note: the calibrator guides for the specific telescopes usually indicate appropriate min and max for uvrange. For example, see the VLA Calibration Manual at: https://science.nrao.edu/facilities/vla/observing/callist for details on the use of standard calibrators for the VLA.