VCSBeam: mwa_plot_calibration

This program is designed to test the effect of various options given in make_mwa_tied_array_beam on the calibration solution. The command line options for mwa_plot_calibration are a subset of those in make_mwa_tied_array_beam:

mwa_plot_calibration -h

usage: mwa_plot_calibration [OPTIONS]

OPTIONS (RTS)

	-m, --metafits=FILE        FILE is the metafits file for the target observation
	-c, --cal-metafits=FILE    FILE is the metafits file pertaining to the calibration solution
	-C, --cal-location=PATH    PATH is the directory (RTS) or the file (OFFRINGA) containing the calibration solution
	-N, --ncoarse_chans=NUM    NUM is the number of coarse channels to include
	-R, --ref-ant=TILENAME     Override the reference tile given in pq_phase_correction.txt for rotating the phases
	                           of the PP and QQ elements of the calibration solution. To turn off phase rotation
	                           altogether, set TILENAME=NONE.
	-U, --PQ-phase=PH,OFFS     Override the phase correction given in pq_phase_correction.txt. PH is given in rad/Hz
	                           and OFFS given in rad, such that, the QQ element of the calibration Jones matrix
	                           for frequency F (in Hz) is multiplied by
	                                exp(PH*F + OFFS)
	                           Setting PH = OFFS = 0 is equivalent to not performing any phase correction
	-X, --cross-terms          Retain the PQ and QP terms of the calibration solution [default: off]

CALIBRATION OPTIONS (OFFRINGA) -- NOT YET SUPPORTED

	-O, --offringa             The calibration solution is in the Offringa format instead of
	                           the default RTS format. In this case, the argument to -C should
	                           be the full path to the binary solution file.

OTHER OPTIONS

	-h, --help                 Print this help and exit
	-V, --version              Print version number and exit

The three key options that this script is useful for testing are the -R, -U, and -X options. If none of these are provided, then the default behaviour is for the relevant values to be drawn from the file RUNTIME/pq_phase_correction.txt, where "RUNTIME" is the path set at VCSBeam compile-time. If there is an entry in pq_phase_correction.txt where the obsid falls between the "From" and "To" times (inclusive), then the values in the "Phase slope" and "Phase offset" columns are used for the -U option, and the value in the "Reference Tile Name" column is used for the -R option. For example, consider the following entry in pq_phase_correction.txt:

#  From_(gpstime) | To_(gpstime) | Phase_slope_(rad/Hz) | Phase_offset_(rad) | Referece Tile Name | Notes
1201478418  1280275218  7.7258e-09   0.4898   LBG8     # From https://wiki.mwatelescope.org/display/MP/Polarimetry (accessed: 19 Aug 2021)

The command

mwa_plot_calibration -m 1240826896_metafits_ppds.fits -c 1240827912.metafits -C /PATH/TO/RTS/OUTPUT -N 24

would be equivalent to

mwa_plot_calibration -m 1240826896_metafits_ppds.fits -c 1240827912.metafits -C /PATH/TO/RTS/OUTPUT -N 24 -U 7.7258e-09,0.4898 -R LBG8

If there is no entry where the obsid of the target obs (in this case, 1240826896) falls between the From and To times, then the default behaviour is for the "dividing through by a reference antenna" (-R) step to be skipped, and for no extra phase slope (-U) to be applied. To force this behaviour (regardless of wheter there is a corresponding entry in pq_phase_correction.txt), the following command line options should be used:

mwa_plot_calibration -m 1240826896_metafits_ppds.fits -c 1240827912.metafits -C /PATH/TO/RTS/OUTPUT -N 24 -U 0,0 -R NONE

Output

The mwa_plot_calibration program outputs the calibration solution as ASCII text with a self-describing (#-commented) header, printed to stdout. To store this output in a file for later plotting, use standard redirection, example:

mwa_plot_calibration -m 1240826896_metafits_ppds.fits -c 1240827912.metafits -C /PATH/TO/RTS/OUTPUT -N 24 -U 0,0 -R NONE > solution.txt

The outputted file can than be used with plot_calibration.py to generate plots such as those shown below.