CASA Contributed Script: vlacal-setjy

This page is currently under development. Please do not use this guide until this message has been removed.

Introduction

Flux-density calibration for the VLA typically involves an observation of one of four primary calibrators: 3C286, 3C48, 3C138 and 3C147. Models for these sources are distributed as part of the CASA package and model visibilities are predicted using the task setjy. The most current models available in setjy are accessible using the flux-density standard Perley Butler 2017 (hereafter PB17), which is based on observations conducted on or before January 2016. See this link for further discussion of VLA flux-density calibration.

Given the recent and significant variability in some primary calibrators (i.e., 3C48 and 3C147) NRAO staff are in the process of creating a new flux-density standard based on more recent observations. Instead of packaging these new models with CASA, NRAO will host a database that is continually updated with the latest monitoring data (having an approximately monthly cadence). A new flux-density standard will be added to the task setjy to make use of these new models (estimated release date 2023). Until the new version of setjy is released, this contributed script vlacal-setjy.py can be executed to obtain the newest models from the database. This casaguide provides documentation and examples of how to use this script.

Obtaining the script

The script vlacal-setjy.py is available for download here. Please save a copy in your local working directory, e.g.,

# in CASA
!wget www.aoc.nrao.edu/~jmarvil/vlacal-setjy.py

Loading the functions

Next, you will want to run the script in CASA, e.g.,

# in CASA
execfile('vlacal-setjy.py')

This will import functions that you can now run from your CASA session. You will need to run the script each time you start CASA if you want these functions to be available (or add the above to startup.py). Note that you will not need to open the script in an editor or make any modifications to it.

Calculating a flux-density ratio

One function provided by this script will calculate the ratio of the PB17 flux to the new NRAO flux standard. This ratio may be of interest to users who have already calibrated their data using the PB17 flux standard. In this case, the ratio could be used to scale the visibility amplitude or the image intensity. The function to calculate this ratio is called vlacal_setjy_calculate_ratio. The following functional arguments will need to be provided:

• source: The string name of the VLA primary calibrator, i.e., one of '3C286', '3C48', '3C138' or '3C147'
• band: The single-letter string name of the VLA receiver band, i.e., one of 'P', 'L', 'S', 'C', 'X', 'U', 'K', 'A' or 'Q'
• date: The date to determine the flux-density scale (typically the date your observation took place), formatted as'YYYY/MM/DD'

For example, for source 3C48 at Ka-band on June 1, 2019 you would run:

# in CASA
vlacal_setjy_calculate_ratio( source='3C48', band='A', date='2019/06/01' )

which will produce the following output:

Obtained flux of 1.074 Jy on mjd 58635.0 for source 3C48 at reference frequency 33.25 GHz
This interpolated flux differs from Perley-Butler 2017 by 32.65%

Based on this output, one could scale their results by a factor of 1.3265 to account for the estimated flux of 3C48 at their time of observation.

Recalibrating your visibilities

The setjy replacement function

Another function provided by this script will fill the MODEL_DATA column of your measurement set. This is intended to replace the running of the task setjy in the VLA calibration procedure. The setjy replacement function is called vlacal_setjy_predict_model_data. The following functional arguments will need to be provided:

• vis: The string name of the measurement set to be processed
• field: The string field ID(s) of the primary calibrator to be processed, e.g., '0'. All selected fields need to be for the same source.
• source: The string name of the VLA primary calibrator corresponding to the field parameter, i.e., one of '3C286', '3C48', '3C138' or '3C147'
• spw: The CASA spectral window selection string to be processed. All SPWs need to be from the same receiver band.
• band: The single-letter string name of the VLA receiver band corresponding to the spw parameter, i.e., one of 'P', 'L', 'S', 'C', 'X', 'U', 'K', 'A' or 'Q'
• date: The date to determine the flux-density scale (typically the date your observation took place), formatted as'YYYY/MM/DD'

If your measurement set contains multiple primary flux calibrators and/or multiple receiver bands then you will need to run the above function once per source/band combination, identifying the appropriate field-source and spw-band relationships for each combination.

Example function usage

For example, for source 3C48 at Ka-band on June 1, 2019 you would run:

# in CASA
vlacal_setjy_predict_model_data( vis='', field='', source='3C48', spw='', band='A', date='2019/06/01' )

which will produce the following output:

Saved modified component list table: 3C48_A_vlacal_2019.42.cl
Running task_ft on data selection:  spw='', field=''