# Difference between revisions of "Polarization Calibration based on CASA pipeline standard reduction: The radio galaxy 3C75-CASA5.4.2"

This CASA Guide is for version 5.4.2-5 of CASA that includes the VLA pipeline and is also verified to work with 5.4.1-32, but not 5.4.0-70 that does not include a pipeline. If you are using a later version of CASA and this is the most recent available guide, then you should be able to use most, if not all, of this tutorial.

## Overview

This CASA guide describes the calibration and imaging of a single-pointing continuum data set taken with the Karl G. Jansky Very Large Array (VLA) of the binary black hole system 3C 75 in Abell 400 cluster of galaxies. [1]. The data were taken as a demonstration for the VLA data reduction workshops under project code TDRW0001. To reduce the dataset size, the data was recorded with a single 1 GHz baseband centered at 3.0 GHz, resulting in 8x128 MHz wide spectral windows with 64 channels each. The observation was set up to allow for full polarization calibration.

## How to Use This CASA Guide

Here are a number of possible ways to run CASA, described in more detail in Getting Started in CASA. In brief, there are at least three different ways to run CASA:

• Pseudo-interactively via task function calls. In this case, all of the desired inputs to a task are provided at once on the CASA command line. This tutorial is made up of such calls, which were developed by looking at the inputs for each task and deciding what needed to be changed from default values. For task function calls, only parameters that you want to be different from their defaults need to be set.
• Non-interactively via a script. A series of task function calls can be combined together into a script and run from within CASA via execfile('scriptname.py'). This and other CASA Tutorial Guides have been designed to be extracted into a script via the script extractor by using the method described at the Extracting_scripts_from_these_tutorials page. Should you decide to use the script generated by the script extractor for this CASA Guide, be aware that it will require some small amount of interaction related to the plotting, occasionally suggesting that you close the graphics window and hitting return in the terminal to proceed. It is, in fact, unnecessary to close the graphics windows (it is suggested that you do so purely to keep your desktop uncluttered).

If you are a relative novice or just new to CASA, it is strongly recommended to work through this tutorial by cutting and pasting the task function calls provided below after you have read all the associated explanations. Work at your own pace, look at the inputs to the tasks to see what other options exist, and read the help files. Later, when you are more comfortable, you might try to extract the script, modify it for your purposes, and begin to reduce other data.

## Obtaining the Data

If starting from scratch, you can obtain the dataset from the NRAO archive and search for the Archive File ID: 'TDRW0001.sb35624494.eb35628826.58395.23719237269'. The uncalibrated visibilities have a size of 12.5 GB.

For those that want to skip the step of obtaining a continuum Stokes I calibrated measurement set, we have created a starting dataset on which the polarization calibration steps and final imaging can be performed: https://casa.nrao.edu/Data/EVLA/TDRW0001/TDRW0001_calibrated.ms.tgz (size: 10 GB). Recommended to use the command line tool wget to download. You will need to untar and unzip the file using the command: 'tar -xzvf TDRW0001_calibrated.ms.tgz'. Then you can skip ahead to the section 'The Observation'.

## Pipeline Calibration of Parallel Hands (RR/LL)

If you start with the uncalibrated visibilities obtained from the archive, you will need to first perform a standard continuum calibration of the parallel-hand (RR/LL) cross-correlation visibilities. In this guide we use the standard VLA pipeline that is packaged with the CASA release. You can find more information on the latest release of the VLA pipeline here: https://science.nrao.edu/facilities/vla/data-processing/pipeline.

In this example, we will not run the pipeline in its standard way but tweak it to force a certain reference antenna. The pipeline typically tries to pick a reference antenna at the center of the array; however this dataset was observed in D array configuration with very short baselines. It was found to be better to use one of the outer antennas for reference, which provides more longer baselines and more stable phase solutions. To set the reference antenna, we specify the refantignore parameter in some of the pipeline tasks to exclude all but the reference antenna, and use a pipeline execution script ('casa_pipescript.py'). Take the script given below and paste it into a text file inside your working directory that also contains the dataset you downloaded from the NRAO archive and name it casa_pipescript.py.

# casa_pipescript.py

__rethrow_casa_exceptions = True
context = h_init()
context.set_state('ProjectSummary', 'proposal_code', 'VLA/null')
context.set_state('ProjectSummary', 'observatory', 'Karl G. Jansky Very Large Array')
context.set_state('ProjectSummary', 'telescope', 'EVLA')
context.set_state('ProjectSummary', 'piname', 'unknown')
context.set_state('ProjectSummary', 'proposal_title', 'unknown')
try:
hifv_importdata(vis=['TDRW0001.sb35624494.eb35628826.58395.23719237269'], session=['session_1'], createmms='automatic', asis='Receiver CalAtmosphere', ocorr_mode='co', nocopy=False, overwrite=False)
hifv_hanning(pipelinemode="automatic")
hifv_flagdata(tbuff=0.0, flagbackup=False, scan=True, fracspw=0.05, intents='*POINTING*,*FOCUS*,*ATMOSPHERE*,*SIDEBAND_RATIO*, *UNKNOWN*, *SYSTEM_CONFIGURATION*, *UNSPECIFIED#UNSPECIFIED*', clip=True, baseband=True, shadow=True, quack=True, edgespw=True, autocorr=True, hm_tbuff='1.5int', template=True, online=True)
hifv_vlasetjy(fluxdensity=-1, scalebychan=True, spix=0, reffreq='1GHz')
hifv_priorcals(tecmaps=False)
hifv_testBPdcals(weakbp=False, refantignore='ea01,ea02,ea03,ea04,ea05,ea06,ea07,ea08,ea09,ea11,ea12,ea13,ea14,ea15,ea16,ea17,ea18,ea19,ea20,ea21,ea22,ea23,ea24,ea26,ea28')
hifv_checkflag(pipelinemode="automatic")
hifv_semiFinalBPdcals(weakbp=False, refantignore='ea01,ea02,ea03,ea04,ea05,ea06,ea07,ea08,ea09,ea11,ea12,ea13,ea14,ea15,ea16,ea17,ea18,ea19,ea20,ea21,ea22,ea23,ea24,ea26,ea28')
hifv_checkflag(checkflagmode='semi')
hifv_semiFinalBPdcals(weakbp=False, refantignore='ea01,ea02,ea03,ea04,ea05,ea06,ea07,ea08,ea09,ea11,ea12,ea13,ea14,ea15,ea16,ea17,ea18,ea19,ea20,ea21,ea22,ea23,ea24,ea26,ea28')
hifv_solint(refantignore='ea01,ea02,ea03,ea04,ea05,ea06,ea07,ea08,ea09,ea11,ea12,ea13,ea14,ea15,ea16,ea17,ea18,ea19,ea20,ea21,ea22,ea23,ea24,ea26,ea28')
hifv_fluxboot(refantignore='ea01,ea02,ea03,ea04,ea05,ea06,ea07,ea08,ea09,ea11,ea12,ea13,ea14,ea15,ea16,ea17,ea18,ea19,ea20,ea21,ea22,ea23,ea24,ea26,ea28')
hifv_finalcals(weakbp=False, refantignore='ea01,ea02,ea03,ea04,ea05,ea06,ea07,ea08,ea09,ea11,ea12,ea13,ea14,ea15,ea16,ea17,ea18,ea19,ea20,ea21,ea22,ea23,ea24,ea26,ea28')
hifv_applycals(flagdetailedsum=True, gainmap=False, flagbackup=True, flagsum=True)
hifv_targetflag(intents='*CALIBRATE*,*TARGET*')
hifv_statwt(pipelinemode="automatic")
hifv_plotsummary(pipelinemode="automatic")
hif_makeimlist(nchan=-1, calcsb=False, intent='PHASE,BANDPASS', robust=-999.0, per_eb=False, calmaxpix=300, specmode='cont', clearlist=True)
hif_makeimages(tlimit=2.0, hm_minbeamfrac=-999.0, hm_dogrowprune=True, hm_negativethreshold=-999.0, calcsb=False, target_list={}, hm_noisethreshold=-999.0, hm_masking='none', hm_minpercentchange=-999.0, parallel='automatic', masklimit=4, hm_lownoisethreshold=-999.0, hm_growiterations=-999, cleancontranges=False, hm_sidelobethreshold=-999.0)
finally:
h_save()


Now that we have the script, we can execute the pipeline. Type on the command line the following.

# On the command line, for your own installation of CASA 5.4.2-5
casa --pipeline --nogui -c casa_pipescript.py

# If using an NRAO computer, to select the right CASA version use instead
casa -r 5.4.2-5 --pipeline --nogui -c casa_pipescript.py


Now you can go and get a cup of coffee or lunch. This is going to take a while. On a beefy computer expect about two hours. Once the pipeline has successfully finished you will see some similar messages on the command line prompt.

2019-03-21 19:18:01 INFO: Plotting pipeline-20190225T152914/html/oussid.s20_0.J0259+0747_ph.S_band.cont.I.iter1.residual.tt0
2019-03-21 19:18:01 INFO: Plotting pipeline-20190225T152914/html/oussid.s20_0.J0259+0747_ph.S_band.cont.I.iter1.model.tt0

2019-03-21 19:18:06 INFO: Saving context to 'pipeline-20190321T171946.context'


In order to be able to continue calibration for polarization, i.e. the cross-hand correlations (RL/LR), on pre-calibrated visibilities, we need to perform some additional steps that remove the parallactic angle correction that was applied by the standard pipeline. To do so, start CASA and execute the following commands.

# In CASA
flagmanager(vis='TDRW0001.sb35624494.eb35628826.58395.23719237269.ms',mode='restore',versionname='applycal_5')

applycal(vis='TDRW0001.sb35624494.eb35628826.58395.23719237269.ms',
antenna='*&*',
gaintable=['TDRW0001.sb35624494.eb35628826.58395.23719237269.ms.hifv_priorcals.s5_2.gc.tbl','TDRW0001.sb35624494.eb35628826.58395.23719237269.ms.hifv_priorcals.s5_3.opac.tbl', 'TDRW0001.sb35624494.eb35628826.58395.23719237269.ms.hifv_priorcals.s5_4.rq.tbl', 'TDRW0001.sb35624494.eb35628826.58395.23719237269.ms.hifv_priorcals.s5_6.ants.tbl', 'TDRW0001.sb35624494.eb35628826.58395.23719237269.ms.hifv_finalcals.s14_2.finaldelay.tbl', 'TDRW0001.sb35624494.eb35628826.58395.23719237269.ms.hifv_finalcals.s14_4.finalBPcal.tbl', 'TDRW0001.sb35624494.eb35628826.58395.23719237269.ms.hifv_finalcals.s14_5.averagephasegain.tbl', 'TDRW0001.sb35624494.eb35628826.58395.23719237269.ms.hifv_finalcals.s14_7.finalampgaincal.tbl', 'TDRW0001.sb35624494.eb35628826.58395.23719237269.ms.hifv_finalcals.s14_8.finalphasegaincal.tbl'],
gainfield=['', '', '', '', '', '', '', '', ''], interp=['', '', '', '', '', 'linear,linearflag', '', '', ''],
spwmap=[[], [], [], [], [], [], [], [], []],
calwt=[False, False, False, False, False, False, False, False, False],
parang=False,
applymode='calflagstrict',
flagbackup=False)

flagdata(vis='TDRW0001.sb35624494.eb35628826.58395.23719237269.ms', mode='rflag', correlation='ABS_LL,RR', intent='*CALIBRATE*', datacolumn='corrected', ntime='scan', combinescans=False, extendflags=False, winsize=3, timedevscale=4.0, freqdevscale=4.0, action='apply', flagbackup=False, savepars=True)
flagdata(vis='TDRW0001.sb35624494.eb35628826.58395.23719237269.ms', mode='rflag', correlation='ABS_LL,RR', intent='*TARGET*', datacolumn='corrected', ntime='scan', combinescans=False, extendflags=False, winsize=3, timedevscale=4.0, freqdevscale=4.0, action='apply', flagbackup=False, savepars=True)

statwt(vis='TDRW0001.sb35624494.eb35628826.58395.23719237269.ms', minsamp=8, datacolumn='corrected', flagbackup=False)

split(vis='TDRW0001.sb35624494.eb35628826.58395.23719237269.ms',outputvis='TDRW0001_calibrated.ms',datacolumn='corrected',spw='2~9')


This applies the flagging state before the final applycal stage of the pipeline, then reapplies the calibration to the corrected column with parang=False, thus disabling the parallactic angle corrections. After that, we rerun target field flagging, and recompute the weights based on the new flags that were applied and split out the corrected column for the target spectral windows. Essentially, we repeated what pipeline tasks hifv_applycals, hifv_targetflag, and hifv_statwt did, but disabling application of parallactic angle corrections. This is the measurement set we will be using in the following to demonstrate polarization calibration.

## The Observation

Before starting the calibration process, we want to get some basic information about the data set. To examine the observing conditions during the observing run, and to find out any known problems with the data, download the observer log. Simply fill in the known observing date (in our case 2018-Oct-04) as both the Start and Stop date and click on the Show Logs button. The relevant log is labelled with the project code, TDRW0001, and can be downloaded as a PDF file. From this, we find the following:

Information from observing log:
Antennas in the D-array may be shadowed at low elevations.  If shadowing
occurs, sensitivity will be affected.

NOTE!: The VLA is still recovering from a long power outage, and these data may
have unusual artifacts, missing antennas or IFs, ect., in them. NRAO staff will
examine the data closely after observing to determine if they meet the criteria for
a successful observation.

Antenna ea05: S-band receiver cooling after work performed, currently 65/177K,
thus we expect lower sensitivity from this antenna.
Antennas ea10, ea12, ea22 do not have good baseline positions
Winds at 7-5 m/s, API RMS phase around 4 deg., 10-20% sky cover, cumuliform and stratiform clouds.


Before beginning our data reduction, we should inspect the pipeline calibration weblog for any obvious issues. You can download the weblog from https://casa.nrao.edu/Data/EVLA/TDRW0001/weblog.tgz or directly access it at https://casa.nrao.edu/Data/EVLA/TDRW0001/pipeline-20190321T171946/html/.

Inside the weblog, you have access to the overview page and the listobs task output that provide some basic information about the data.

You will note that there are four sources observed. Here the various sources are introduced briefly, with more detail contained in the sections below in which they are used

• 0137+331=3C48, which will serve as a calibrator for the visibility amplitudes, i.e., it is assumed to have a precisely known flux density, the spectral bandpass, and the polarization position angle;
• J0259+0747, which will serve as a calibrator for the visibility phases and can be used to determine the instrumental polarization;
• J2355+4950, which can serve as a secondary instrumental polarization calibrator or to check residual instrumental polarization, and;
• 3C75, which is the science target.

================================================================================
MeasurementSet Name:  /lustre/aoc/sciops/dmedlin/4fs/TDRW0001.sb35624494.eb35628826.58395.23719237269.ms      MS Version 2
================================================================================
Observer: Dr. Emmanuel Momjian     Project: uid://evla/pdb/35621723
Observation: EVLA
Data records: 5752188       Total elapsed time = 10270 seconds
Observed from   04-Oct-2018/05:41:35.0   to   04-Oct-2018/08:32:45.0 (UTC)

ObservationID = 0         ArrayID = 0
Date        Timerange (UTC)          Scan  FldId FieldName             nRows     SpwIds   Average Interval(s)    ScanIntent
04-Oct-2018/05:41:35.0 - 05:42:31.0     1      0 0137+331=3C48            39312  [0,1]  [1, 1] [SYSTEM_CONFIGURATION#UNSPECIFIED]
05:42:32.0 - 05:47:30.0     2      0 0137+331=3C48           209196  [0,1]  [1, 1] [SYSTEM_CONFIGURATION#UNSPECIFIED]
05:47:35.0 - 05:48:30.0     3      0 0137+331=3C48            30888  [2,3,4,5,6,7,8,9]  [5, 5, 5, 5, 5, 5, 5, 5] [SYSTEM_CONFIGURATION#UNSPECIFIED]
05:48:35.0 - 05:49:00.0     4      0 0137+331=3C48            14040  [2,3,4,5,6,7,8,9]  [5, 5, 5, 5, 5, 5, 5, 5] [SYSTEM_CONFIGURATION#UNSPECIFIED]
05:49:05.0 - 05:53:25.0     5      0 0137+331=3C48           146016  [2,3,4,5,6,7,8,9]  [5, 5, 5, 5, 5, 5, 5, 5] [CALIBRATE_BANDPASS#UNSPECIFIED,CALIBRATE_FLUX#UNSPECIFIED,CALIBRATE_POL_ANGLE#UNSPECIFIED]
05:53:30.0 - 05:57:55.0     6      1 J2355+4950              148824  [2,3,4,5,6,7,8,9]  [5, 5, 5, 5, 5, 5, 5, 5] [CALIBRATE_AMPLI#UNSPECIFIED,CALIBRATE_PHASE#UNSPECIFIED]
05:58:00.0 - 06:03:55.0     7      2 J0259+0747              199368  [2,3,4,5,6,7,8,9]  [5, 5, 5, 5, 5, 5, 5, 5] [CALIBRATE_AMPLI#UNSPECIFIED,CALIBRATE_PHASE#UNSPECIFIED,CALIBRATE_POL_LEAKAGE#UNSPECIFIED]
06:04:00.0 - 06:18:55.0     8      3 3C75                    502632  [2,3,4,5,6,7,8,9]  [5, 5, 5, 5, 5, 5, 5, 5] [OBSERVE_TARGET#UNSPECIFIED]
06:19:00.0 - 06:20:10.0     9      2 J0259+0747               39312  [2,3,4,5,6,7,8,9]  [5, 5, 5, 5, 5, 5, 5, 5] [CALIBRATE_AMPLI#UNSPECIFIED,CALIBRATE_PHASE#UNSPECIFIED,CALIBRATE_POL_LEAKAGE#UNSPECIFIED]
06:20:15.0 - 06:35:05.0    10      3 3C75                    499824  [2,3,4,5,6,7,8,9]  [5, 5, 5, 5, 5, 5, 5, 5] [OBSERVE_TARGET#UNSPECIFIED]
06:35:10.0 - 06:36:20.0    11      2 J0259+0747               39312  [2,3,4,5,6,7,8,9]  [5, 5, 5, 5, 5, 5, 5, 5] [CALIBRATE_AMPLI#UNSPECIFIED,CALIBRATE_PHASE#UNSPECIFIED,CALIBRATE_POL_LEAKAGE#UNSPECIFIED]
06:36:25.0 - 06:51:20.0    12      3 3C75                    502632  [2,3,4,5,6,7,8,9]  [5, 5, 5, 5, 5, 5, 5, 5] [OBSERVE_TARGET#UNSPECIFIED]
06:51:25.0 - 06:52:30.0    13      2 J0259+0747               36504  [2,3,4,5,6,7,8,9]  [5, 5, 5, 5, 5, 5, 5, 5] [CALIBRATE_AMPLI#UNSPECIFIED,CALIBRATE_PHASE#UNSPECIFIED,CALIBRATE_POL_LEAKAGE#UNSPECIFIED]
06:52:35.0 - 07:07:30.0    14      3 3C75                    502632  [2,3,4,5,6,7,8,9]  [5, 5, 5, 5, 5, 5, 5, 5] [OBSERVE_TARGET#UNSPECIFIED]
07:07:35.0 - 07:08:45.0    15      2 J0259+0747               39312  [2,3,4,5,6,7,8,9]  [5, 5, 5, 5, 5, 5, 5, 5] [CALIBRATE_AMPLI#UNSPECIFIED,CALIBRATE_PHASE#UNSPECIFIED,CALIBRATE_POL_LEAKAGE#UNSPECIFIED]
07:08:50.0 - 07:23:40.0    16      3 3C75                    499824  [2,3,4,5,6,7,8,9]  [5, 5, 5, 5, 5, 5, 5, 5] [OBSERVE_TARGET#UNSPECIFIED]
07:23:45.0 - 07:26:25.0    17      2 J0259+0747               89856  [2,3,4,5,6,7,8,9]  [5, 5, 5, 5, 5, 5, 5, 5] [CALIBRATE_AMPLI#UNSPECIFIED,CALIBRATE_PHASE#UNSPECIFIED,CALIBRATE_POL_LEAKAGE#UNSPECIFIED]
07:26:30.0 - 07:41:25.0    18      3 3C75                    502632  [2,3,4,5,6,7,8,9]  [5, 5, 5, 5, 5, 5, 5, 5] [OBSERVE_TARGET#UNSPECIFIED]
07:41:30.0 - 07:42:40.0    19      2 J0259+0747               39312  [2,3,4,5,6,7,8,9]  [5, 5, 5, 5, 5, 5, 5, 5] [CALIBRATE_AMPLI#UNSPECIFIED,CALIBRATE_PHASE#UNSPECIFIED,CALIBRATE_POL_LEAKAGE#UNSPECIFIED]
07:42:45.0 - 07:57:35.0    20      3 3C75                    499824  [2,3,4,5,6,7,8,9]  [5, 5, 5, 5, 5, 5, 5, 5] [OBSERVE_TARGET#UNSPECIFIED]
07:57:40.0 - 07:58:50.0    21      2 J0259+0747               39312  [2,3,4,5,6,7,8,9]  [5, 5, 5, 5, 5, 5, 5, 5] [CALIBRATE_AMPLI#UNSPECIFIED,CALIBRATE_PHASE#UNSPECIFIED,CALIBRATE_POL_LEAKAGE#UNSPECIFIED]
07:58:55.0 - 08:13:50.0    22      3 3C75                    502632  [2,3,4,5,6,7,8,9]  [5, 5, 5, 5, 5, 5, 5, 5] [OBSERVE_TARGET#UNSPECIFIED]
08:13:55.0 - 08:15:05.0    23      2 J0259+0747               39312  [2,3,4,5,6,7,8,9]  [5, 5, 5, 5, 5, 5, 5, 5] [CALIBRATE_AMPLI#UNSPECIFIED,CALIBRATE_PHASE#UNSPECIFIED,CALIBRATE_POL_LEAKAGE#UNSPECIFIED]
08:15:10.0 - 08:30:00.0    24      3 3C75                    499824  [2,3,4,5,6,7,8,9]  [5, 5, 5, 5, 5, 5, 5, 5] [OBSERVE_TARGET#UNSPECIFIED]
08:30:05.0 - 08:32:45.0    25      2 J0259+0747               89856  [2,3,4,5,6,7,8,9]  [5, 5, 5, 5, 5, 5, 5, 5] [CALIBRATE_AMPLI#UNSPECIFIED,CALIBRATE_PHASE#UNSPECIFIED,CALIBRATE_POL_LEAKAGE#UNSPECIFIED]
(nRows = Total number of rows per scan)
Fields: 4
ID   Code Name                RA               Decl           Epoch   SrcId      nRows
0    NONE 0137+331=3C48       01:37:41.299431 +33.09.35.13299 J2000   0         439452
1    NONE J2355+4950          23:55:09.458169 +49.50.08.34001 J2000   1         148824
2    NONE J0259+0747          02:59:27.076633 +07.47.39.64322 J2000   2         651456
3    NONE 3C75                02:57:42.630000 +06.01.04.80000 J2000   3        4512456
Spectral Windows:  (10 unique spectral windows and 1 unique polarization setups)
SpwID  Name          #Chans   Frame   Ch0(MHz)  ChanWid(kHz)  TotBW(kHz) CtrFreq(MHz) BBC Num  Corrs
0      EVLA_C#A0C0#0     64   TOPO    4832.000      2000.000    128000.0   4895.0000       12  RR  RL  LR  LL
1      EVLA_C#B0D0#1     64   TOPO    4960.000      2000.000    128000.0   5023.0000       15  RR  RL  LR  LL
2      EVLA_S#A0C0#2     64   TOPO    2488.000      2000.000    128000.0   2551.0000       12  RR  RL  LR  LL
3      EVLA_S#A0C0#3     64   TOPO    2616.000      2000.000    128000.0   2679.0000       12  RR  RL  LR  LL
4      EVLA_S#A0C0#4     64   TOPO    2744.000      2000.000    128000.0   2807.0000       12  RR  RL  LR  LL
5      EVLA_S#A0C0#5     64   TOPO    2872.000      2000.000    128000.0   2935.0000       12  RR  RL  LR  LL
6      EVLA_S#A0C0#6     64   TOPO    3000.000      2000.000    128000.0   3063.0000       12  RR  RL  LR  LL
7      EVLA_S#A0C0#7     64   TOPO    3128.000      2000.000    128000.0   3191.0000       12  RR  RL  LR  LL
8      EVLA_S#A0C0#8     64   TOPO    3256.000      2000.000    128000.0   3319.0000       12  RR  RL  LR  LL
9      EVLA_S#A0C0#9     64   TOPO    3384.000      2000.000    128000.0   3447.0000       12  RR  RL  LR  LL
Sources: 34
ID   Name                SpwId RestFreq(MHz)  SysVel(km/s)
0    0137+331=3C48       0     -              -
0    0137+331=3C48       1     -              -
0    0137+331=3C48       2     -              -
0    0137+331=3C48       3     -              -
0    0137+331=3C48       4     -              -
0    0137+331=3C48       5     -              -
0    0137+331=3C48       6     -              -
0    0137+331=3C48       7     -              -
0    0137+331=3C48       8     -              -
0    0137+331=3C48       9     -              -
1    J2355+4950          2     -              -
1    J2355+4950          3     -              -
1    J2355+4950          4     -              -
1    J2355+4950          5     -              -
1    J2355+4950          6     -              -
1    J2355+4950          7     -              -
1    J2355+4950          8     -              -
1    J2355+4950          9     -              -
2    J0259+0747          2     -              -
2    J0259+0747          3     -              -
2    J0259+0747          4     -              -
2    J0259+0747          5     -              -
2    J0259+0747          6     -              -
2    J0259+0747          7     -              -
2    J0259+0747          8     -              -
2    J0259+0747          9     -              -
3    3C75                2     -              -
3    3C75                3     -              -
3    3C75                4     -              -
3    3C75                5     -              -
3    3C75                6     -              -
3    3C75                7     -              -
3    3C75                8     -              -
3    3C75                9     -              -
Antennas: 27:
ID   Name  Station   Diam.    Long.         Lat.                Offset from array center (m)                ITRF Geocentric coordinates (m)
East         North     Elevation               x               y               z
0    ea01  W06       25.0 m   -107.37.15.6  +33.53.56.4       -275.8278     -166.7360       -2.0595 -1601447.195400 -5041992.497600  3554739.694800
1    ea02  W04       25.0 m   -107.37.10.8  +33.53.59.1       -152.8711      -83.7955       -2.4675 -1601315.900500 -5041985.306670  3554808.309400
2    ea03  W07       25.0 m   -107.37.18.4  +33.53.54.8       -349.9804     -216.7527       -1.7877 -1601526.383100 -5041996.851000  3554698.331400
3    ea04  N04       25.0 m   -107.37.06.5  +33.54.06.1        -42.6260      132.8521       -3.5428 -1601173.981600 -5041902.657800  3554987.528200
4    ea05  E05       25.0 m   -107.36.58.4  +33.53.58.8        164.9709      -92.7908       -2.5361 -1601014.465100 -5042086.235700  3554800.804900
5    ea06  N06       25.0 m   -107.37.06.9  +33.54.10.3        -54.0745      263.8800       -4.2325 -1601162.598500 -5041828.990800  3555095.895300
6    ea07  E04       25.0 m   -107.37.00.8  +33.53.59.7        102.8035      -63.7671       -2.6299 -1601068.794800 -5042051.918100  3554824.842700
7    ea08  E01       25.0 m   -107.37.05.7  +33.53.59.2        -23.8867      -81.1272       -2.5808 -1601192.486700 -5042022.840700  3554810.460900
8    ea09  N05       25.0 m   -107.37.06.7  +33.54.08.0        -47.8569      192.6072       -3.8789 -1601168.794400 -5041869.042300  3555036.937000
9    ea10  E08       25.0 m   -107.36.48.9  +33.53.55.1        407.8379     -206.0064       -3.2255 -1600801.917500 -5042219.370600  3554706.449200
10   ea11  N07       25.0 m   -107.37.07.2  +33.54.12.9        -61.1072      344.2424       -4.6414 -1601155.630600 -5041783.816000  3555162.366400
11   ea12  E07       25.0 m   -107.36.52.4  +33.53.56.5        318.0401     -164.1704       -2.6834 -1600880.582300 -5042170.386600  3554741.476400
12   ea13  W02       25.0 m   -107.37.07.5  +33.54.00.9        -67.9810      -26.5266       -2.7142 -1601225.261900 -5041980.363990  3554855.705700
13   ea14  E09       25.0 m   -107.36.45.1  +33.53.53.6        506.0539     -251.8836       -3.5735 -1600715.958300 -5042273.202200  3554668.175800
14   ea15  N03       25.0 m   -107.37.06.3  +33.54.04.8        -39.1086       93.0234       -3.3585 -1601177.399560 -5041925.041300  3554954.573300
15   ea16  E02       25.0 m   -107.37.04.4  +33.54.01.1          9.8042      -20.4562       -2.7822 -1601150.083300 -5042000.626900  3554860.706200
16   ea17  N09       25.0 m   -107.37.07.8  +33.54.19.0        -77.4340      530.6515       -5.5829 -1601139.481300 -5041679.026500  3555316.554900
17   ea18  W09       25.0 m   -107.37.25.2  +33.53.51.0       -521.9447     -332.7673       -1.2061 -1601710.016800 -5042006.914600  3554602.360000
18   ea19  W05       25.0 m   -107.37.13.0  +33.53.57.8       -210.1007     -122.3814       -2.2582 -1601377.012800 -5041988.659800  3554776.399200
19   ea20  N02       25.0 m   -107.37.06.2  +33.54.03.5        -35.6257       53.1906       -3.1311 -1601180.861780 -5041947.450400  3554921.638900
20   ea21  N01       25.0 m   -107.37.06.0  +33.54.01.8        -30.8742       -1.4746       -2.8653 -1601185.628465 -5041978.158516  3554876.414800
21   ea22  W03       25.0 m   -107.37.08.9  +33.54.00.1       -105.3218      -51.7280       -2.6013 -1601265.134100 -5041982.547450  3554834.851200
22   ea23  E06       25.0 m   -107.36.55.6  +33.53.57.7        236.9085     -126.3395       -2.4685 -1600951.579800 -5042125.894100  3554772.996600
23   ea24  W08       25.0 m   -107.37.21.6  +33.53.53.0       -432.1080     -272.1502       -1.5080 -1601614.082500 -5042001.654800  3554652.505900
24   ea25  N08       25.0 m   -107.37.07.5  +33.54.15.8        -68.9105      433.1823       -5.0689 -1601147.943900 -5041733.832200  3555235.945600
25   ea26  E03       25.0 m   -107.37.02.8  +33.54.00.5         50.6698      -39.4668       -2.7317 -1601114.356200 -5042023.141200  3554844.955400
26   ea28  W01       25.0 m   -107.37.05.9  +33.54.00.5        -27.3603      -41.2944       -2.7520 -1601189.030040 -5042000.479400  3554843.427200


Note that the antenna IDs (which are numbered sequentially up to the total number of antennas in the array; 0 through 26 in this instance) do not correspond to the actual antenna names (ea01 through ea28; these numbers correspond to those painted on the side of the antennas). The antennas can be referenced using either convention; antenna='22' would correspond to ea23, whereas antenna='ea22' would correspond to ea22. Note that the antenna numbers in the observer log correspond to the actual antenna names, i.e., the 'ea??' numbers given in listobs.

Both to get a sense of the array, as well as identify the location of the antenna that was picked by the pipeline for parallel hand calibration, have a look at the antenna setup page. Generally, for calibration purposes, you would prefer to select an antenna that is close to the center of the array (and that is not listed in the operator's log as having had problems!). As noted above, in a compact configuration there is a benefit to choose an outer antenna to increase the bias toward longer baselines.

At this point it is also a good idea to check the quality of the pipeline calibration. Go to the task overview page and pay particular attention to hifv_finalcals and hifv_plotsummary. Try to see if you can recognize which reference antenna was picked. For more details on the pipeline output you can have a look at the VLA CASA Pipeline Guide. Going forward we assume that the pipeline calibration is good and we can use it as a starting point for further calibration steps focusing on polarization calibration and imaging.

## Examining and Editing the Data

At this point we must start CASA. If you have not used CASA before, some helpful tips are available on the Getting Started in CASA page.

It is always a good idea to examine the data before jumping straight into calibration. From the observer's log there were no major issues noted, besides a potentially warm receiver on antenna ea05. Even though the pipeline did a good job of calibrating and flagging the data, it isn't perfect. From the pipeline weblog, looking at the final amplitude gain calibration vs time plots in hifv_finalcals, we can see that during the second half of the observation antennas ea03, ea12, and ea16 shows some gain instability; otherwise there are no issues identified at this point.

Start by inspecting these three particular antennas using the CASA task plotms, plot frequency against amplitude and frequency against time for the parallel hands, iterate over field or scan, and note if you find something at odds.

# In CASA
plotms(vis='TDRW0001_calibrated.ms', selectdata=True, correlation='RR,LL', averagedata=True, avgchannel='64', coloraxis='field')

Figure 1: Overview of the observation: amplitude vs time, color-coded by field.
• selectdata=True : One can choose to plot only selected subsets of the data.
• correlation='RR,LL' : Plot only the left- and right-handed polarization products. The cross-terms ('RL' and 'LR') will be close to zero for non-polarized sources.
• averagedata=True: One can choose to average data points before plotting them.
• avgchannel='64' : With this plot, we are mainly interested in the fields vs time. Averaging over all 64 channels in the spectral window makes the plotting faster.
• coloraxis='field' : Color-code the plotting symbols by field name/number.

The default x- and y-axis parameters are 'time' and 'amp', so the above call to plotms produces an amplitude vs time plot of the data for a selected subset of the data (if desired) and with data averaging (if desired). Many other values have also been left to defaults, but it is possible to select them from within the plotms GUI.

Task plotms allows one to select and view the data in many ways. Figure 1 shows the result of running plotms with the field selection discussed above. You can quickly see that the first source observed, 3C48 (the primary flux density and polarization angle calibrator source), is the brightest source in this observation. The next brightest is the second source observed, J2355+4950, a CSO and the secondary instrumental polarization calibrator. The complex gain calibrator J0259+0747 (shown in orange) is around 1 Jy. The target scans on 3C75 are colored in green. The spread of amplitudes is primarily due to the presence of extended structure, thus every baseline sees a slightly different amplitude.

Across the top of the left panel of the GUI are a set of tabs labelled Plot, Flag, Tools, Annotate, and Options. By default, the Plot tab is visible. There are a number of tabs running down the side of the left hand panel: Data, Calibration, Axes, Page, Transform, Display, and Canvas; these allow you to make changes to the plotting selection without having to re-launch plotms. Even if it was started with xaxis=' ' (defaulting to 'time'), you can choose a different X-axis by selecting the Axes tab, then using the dropdown menu to switch (for example) to xaxis='Frequency' (to get something sensible when plotting with frequency, channel averaging must be turned off).

You should spend several minutes displaying the data in various formats. You can save the version of the plotms plot as a graphics file by using the menu bar in the plotms GUI to select the Export... option under the Export menu.

Another example of using plotms for a quick look at your data, select the Data tab and specify field 2 (the complex gain calibrator J0259+0747) to display data associated with the target, then select the Axes tab and change the X-axis to be UVdist (baseline length in meters). Remove the channel averaging (Data tab), and plot the data using the Plot button at the bottom of the plotms GUI. The important observation is that the amplitude distribution is relatively constant as a function of UV distance or baseline length (i.e., $\displaystyle{ \sqrt{u^2+v^2} }$ ) (see Figure 2A). A relatively constant visibility amplitude as a function of baseline length means that the source is very nearly a point source. (The Fourier transform of a point source, i.e. a delta function, is a constant function.) You can see occasional spikes in the calibrated amplitudes. This is most likely caused by radio frequency interference that correlates on certain baselines. We will get to those further in the guide.

By contrast, if you make a similar plot for field 3 (our target 3C 75), the result is a visibility function that falls rapidly with increasing baseline length. Figure 2B shows this example, including time averaging of '1e6' seconds (any large number that encompasses more than a full scan will do). Such a visibility function indicates a highly resolved source. The baseline length at which the visibility function falls to some fiducial value (e.g., 1/2 of its peak value) gives a rough estimate of the angular scale of the source (Angular scale [in radians] ~ 1/baseline [in wavelengths]). To plot baseline length in wavelengths rather than meters, select UVwave as the X-axis parameter.

A final example is shown in Figure 2C. In this example, we have elected to show phase as a function of (frequency) channel for a single baseline (antenna='ea01&ea21' ) on the bandpass calibrator, field 0. If you choose to iterate by baseline (e.g., antenna='ea01' and iteraxis='baseline' ), you can see similar phase-frequency variations on all baselines. They center around zero phase, since we are looking at the calibrated visibilities, you are seeing, however, a butterfly shaped pattern with phase noise higher toward the channel edges. This pattern is due to a small mismatch in the delay measurement timing (also known as 'delay clunking') which is an internally generated effect and is typically averaged out over time.

 Figure 2A: plotms view of amp vs. uvdist of J0259+0747, a point source Figure 2B: plotms view of amp vs. uvwave of 3C 75, a resolved source Figure 2C: plotms view of phase vs. channel on one baselines, showing phase delay across the calibrated bandpass

You can find similar plots in the CASA pipeline weblog under the task hifv_plotsummary. At this stage the pipeline has taken care of most of the calibration; there might be some remaining issues, though, that were not caught by the pipeline.

Figure 3: datastream view of MS

One final useful plot we will make is a datastream plot of the antenna2 in a baseline for the data versus ea01. This shows, assuming that ea01 is in the entire observation, when various antennas drop out (see Figure 3).

# In CASA
plotms(vis='TDRW0001_calibrated.ms',field='',correlation='RR,LL',
timerange='',antenna='ea01',spw='0:31',
xaxis='time',yaxis='antenna2',
plotrange=[-1,-1,0,26],coloraxis='field')


From this display you can immediately that flagging performed by the pipeline is present. In the following we note on a couple issues that you might have found and will take care of those through additional flagging.

Issues that you might find:
- ea12, scan 17: amplitude spike at the end of the scan.
- Residual RFI


We can flag this time period, by invoking the casa task flagdata. It is also a good idea to save the original flags before performing any flagging by setting flagbackup=True.

# In CASA
flagdata(vis='TDRW0001_calibrated.ms', flagbackup=True, mode='manual', antenna='ea12',scan='17',timerange='07:25:57~07:26:18')


You can check the effect of this flagging by replotting Figure 2A. The spikes we saw before on some baselines should have disappeared. If you plot frequency against amplitude without averaging, however, you will still see some channels with interference that we will need to flag, especially on the instrumental polarization calibrators. Polarization calibration is very sensitive to interference, especially in the cross-hand correlations RL,LR. The pipeline does not (yet) do a good job at this, therefore we will need to cover some additional flagging steps in the next section.

At first, we try to get a good sense of additional flagging that might be needed by plotting frequency against amplitude for the RR,LL and RL,LR polarizations of our calibrators, fields 0 through 2. In particular we need to pay attention to RL,LR (see Figure 4A). We will perform additional flagging on the target field at a later stage.

# In CASA
# for parallel hands
plotms(vis='TDRW0001_calibrated.ms',xaxis='frequency',yaxis='amplitude',field='0~2',correlation='RR,LL')
# for cross-hands
plotms(vis='TDRW0001_calibrated.ms',xaxis='frequency',yaxis='amplitude',field='0~2',correlation='RL,LR')

 Figure 4a: plotms view of calibrators freq vs. amp RL/LR before additional flagging Figure 4b: plotms view of calibrators freq vs. amp RL/LR after rflag

Since we are dealing with point sources, we do not have to worry about overflagging of shorter baselines, so we can run flagdata with mode='rflag' over the calibrator fields and cross-hand correlations to remove any residual RFI. For completeness, we also use mode='tfcrop' to reduce the amount of residual RFI in the parallel hands. This is not strictly needed at this point, since the polarization calibration is based on the cross-hand correlations.

# In CASA

# for the parallel hands
flagdata(vis='TDRW0001_calibrated.ms',
mode='tfcrop',
field='0~2',
correlation='',
freqfit='line',
extendflags=False,
flagbackup=False)

# for the cross-hands
flagdata(vis='TDRW0001_calibrated.ms',
mode='rflag',
datacolumn='data',
field='0~2',
correlation='RL,LR',
extendflags=True,
flagbackup=False)


As you can see in Figure 4B, this additional flagging step took care of most of the obvious residual RFI. We are now ready to move on to calibrate the visibilities for linear polarization.

## Polarization Calibration

Polarization calibration is done in three steps:

• First, we determine the instrumental delay between the two polarization outputs;
• Second, we solve for the instrumental polarization (the frequency-dependent leakage terms ('D-terms')), using either an unpolarized source or a source which has sufficiently good parallactic angle coverage;
• Third, we solve for the polarization position angle using a source with a known polarization position angle (we use 3C48 here).

For information on polarization calibrators suitable for VLA observations, see the VLA Observing Guide on Polarimetry. The CASA related documentation also provides helpful information on polarization calibration steps and the different options that are available.

Before solving for the calibration solutions, we first use setjy to set the polarization model for our polarized position-angle calibrator. The pipeline only set the total intensity of the flux density calibrator source 3C48, which did not include any polarization information. This source is known to have a fairly stable linear fractional polarization (measured to be 2% in S-band around the time of the observations), a polarization position angle of -100 degrees at 3 GHz, and a rotation measure of -68 rad/m^2. Note at higher frequencies, 3C48 has had an outburst in 2017 and thus is expected to show a significant degree of variability. Since we have applied the pipeline calibration and not corrected for parallactic angle, we can continue polarization calibration using a split measurement set.

The setjy task will calculate the values of Stokes Q and U (in the reference channel) for user inputs of the reference frequency, Stokes I, polarization fraction, polarization angle, and rotation measure. The setjy input parameters can be obtained from Perley & Butler (2017) for Stokes I information and Perley & Butler (2013) for polarization information. Other sources can also be consulted, such as archival observations of variable polarization calibrators available under the project code TPOL0003 or TCAL0009. It is possible to capture a frequency variation in Q, U, and alpha terms by providing coefficients of polynomial expansion for polarization fraction, polarization angle, and spectral index as a function of frequency. At this time, it is left to the user to derive these coefficients, which can be accomplished by fitting a polynomial to observed values of the polarization fraction (here also called polarization index), polarization angle, and flux density (for the case of spectral index). Updated values of the broad band polarimetric information for the four calibration sources 3C48, 3C138, 3C147, and 3C286 (Of these sources, 3C48, 3C138, and 3C147 have been noticed to be variable) can be found at (https://science.nrao.edu/facilities/vla/docs/manuals/oss/performance/fdscale) and at (https://science.nrao.edu/facilities/vla/docs/manuals/obsguide/modes/pol). These coefficients are then passed to the setjy task as lists along with the reference frequency and the Stokes I flux density.

The calibrator used for this guide, 3C48, has a rotation measure and thus changes its Q and U with frequency. Therefore, for our purposes, it is not sufficient to use only the first Taylor term of the expansion. For deriving the setjy input parameters you can consult the setjy CASA documentation. Currently setjy only supports unresolved polarized emission models assuming that the Stokes I,Q,U peak are co-located on the sky. This is not necessarily the case for more complicated objects or even for 3C48 in extended VLA configurations.

# In CASA

# Reference Frequency for fit values
reffreq = '3.0GHz'
# Stokes I flux density
I =        8.45650174
# Spectral Index
alpha =    [-0.90366565, -0.14262821]
# Polarization Fraction
polfrac = [0.021429,0.0391826,0.00234878,-0.0230125]
# Polarization Angle
polangle = [1.4215,1.36672,-2.12678,3.48384,-2.71914]

setjy(vis='TDRW0001_calibrated.ms',
field='0137+331=3C48',
spw='',
selectdata=False,
timerange="",
scan="",
intent="",
observation="",
scalebychan=True,
standard="manual",
model="",
modimage="",
listmodels=False,
fluxdensity=[I,0,0,0],
spix=alpha,
reffreq=reffreq,
polindex=polfrac,
polangle=polangle,
rotmeas=0,
fluxdict={},
useephemdir=False,
interpolation="nearest",
usescratch=True,
ismms=False,
)

• field='0137+331=3C48' : if the flux density calibrator is not specified then all sources will be assumed to have the input model parameters.
• standard='manual' : the user will supply the flux density, spectral index, and polarization parameters rather than giving a model (the CASA models currently do not include polarization).
• fluxdensity=[I,0,0,0] : you may provide values of Q and U rather than having setjy calculate them.However, if you set Q and U as input using the fluxdensity parameter, then the first value given in polindex or polangle will be ignored.
• spix=[-0.90366565, -0.14262821] : set the spectral index using the value above. This will apply to all non-zero Spokes parameters. In this example, we only use the first two coefficients of the Taylor expansion.
• reffreq='3.0GHz' : The reference frequency for the input Stokes values.
• polindex=[0.021429,0.0391826,0.00234878,-0.0230125 : The coefficients of polynomial expansion for the polarization index as a function of frequency.
• polangle=[1.4215,1.36672,-2.12678,3.48384,-2.71914] : The coefficients of polynomial expansion for the polarization angle as a function of frequency.
• scalebychan=True: This allows setjy to compute unique values per channel, rather than applying the reference frequency values to the entire spectral window.
• usescratch=True: DO create/use the MODEL_DATA column explicitly. (usescratch=False saves disk space by not filling the model column)

The Stokes V flux has been set to zero, corresponding to no circular polarization.

setjy returns a Python dictionary (CASA record) that reports the Stokes I, Q, U and V terms. This is reported to the CASA command line window:

{'0': {'0': {'fluxd': array([ 9.99287353, -0.08937082,  0.11939692,  0.        ])},
'1': {'fluxd': array([ 9.55959057, -0.11709484,  0.10568676,  0.        ])},
'2': {'fluxd': array([ 9.16182831, -0.13997047,  0.08921149,  0.        ])},
'3': {'fluxd': array([ 8.7953302 , -0.15846661,  0.07143732,  0.        ])},
'4': {'fluxd': array([ 8.45650174, -0.1731959 ,  0.05330882,  0.        ])},
'5': {'fluxd': array([ 8.14228548, -0.1847571 ,  0.03537654,  0.        ])},
'6': {'fluxd': array([ 7.85006343, -0.193661  ,  0.01792025,  0.        ])},
'7': {'fluxd': array([  7.57758019e+00,  -2.00307499e-01,   1.05166484e-03,
0.00000000e+00])},
'fieldName': '0137+331=3C48'},
'format': "{field Id: {spw Id: {fluxd: [I,Q,U,V] in Jy}, 'fieldName':field name }}"}


Alternatively, you may capture this dictionary in a return variable, if you call setjy as myset=setjy(...).

We can see the results in the model column in plotms (Figure 5A) showing the model source spectrum:

# In CASA
plotms(vis='TDRW0001_calibrated.ms',field='0',correlation='RR',
timerange='',antenna='ea01&ea02',
xaxis='frequency',yaxis='amp',ydatacolumn='model')


We can see this translates to the spectrum in QU (Figure 5B):

# In CASA
plotms(vis='TDRW0001_calibrated.ms',field='0',correlation='RL',
timerange='',antenna='ea01&ea02',
xaxis='frequency',yaxis='amp',ydatacolumn='model')


Finally, our R-L phase difference is constant at 66 degrees (twice the polarization angle) as desired (Figure 5C):

# In CASA
plotms(vis='TDRW0001_calibrated.ms',field='0',correlation='RL',
timerange='',antenna='ea01&ea02',
xaxis='frequency',yaxis='phase',ydatacolumn='model')