Polcal worker description

[francescaLoi]

This is the description that I wrote for the polcal worker. I can split it in two: one about the polcal worker itself and the other about pipeline workflow for polarization.

WORKER DESCRIPTION The implemented methods to calibrate polarization are three and are all based on CASA tasks:

1. we calibrate the leakage with an unpolarized source and the phase with a known polarized source (i.e. 3C138 or 3C286).
2. we calibrate both the leakage and the phase with a known polarized source (i.e. 3C138 or 3C286). This method is useful because there are only two well known unpolarized source in the southern sky (i.e. J1939-6342, J0408-6545).
3. we calibrate both the leakage and the phase with a polarized source without assuming a model. In this case we need to have a good coverage of the parallactic angle (so 3 or more scans at different PA). This could be useful because we do not always have a known polarized source in the sky and with this method we can derive the model for the polarized source by fitting against the PAs.

If fcal is the known unpolarized source, and xcal the polarized source, the steps to calibrate the polarization with polcal are the following:

1. solve for the xcal gain phase (and amplitude if we are calibrating with method 2 or 3)
2. solve for the crosshand delay (KCROSS) with xcal
3. solve for the phase (Xf) with xcal
4. solve for the leakage (Df) with fcal for method 1, xcal for methods 2 and 3

Method 3 requires extra-steps to derive the xcal model but the logic is almost the same and follows this ALMA guide https://casaguides.nrao.edu/index.php/3C286_Band6Pol_Calibration_for_CASA_5.1.

There is an additional method in the polcal worker which calibrates only the leakage. This is done if pol_calib: none.

POLARIZATION CALIBRATION WORKFLOW The simplest pipeline workflow to obtain spectro-polarimetric continuum images consists in these steps:

1. split the calibrators from the MS with the transform worker
2. flag with the flag worker
3. calibrate the parallel terms with the crosscal worker (note that here we do not correct the parallactic angle)
4. calibrate polarization with the polcal worker
5. split the target applying the crosscal and polcal solutions with the transform worker (here parallactic angle de-rotation is applied by default)
6. imaging and selfcal of the target with the selfcal worker (only total intensity imaging is available at the moment).

Note that if you are following the first method and you split the cross calibrated MS before the polcal worker, you need to fill the model column with set_model_leakage: True in the config file. This is not necessary if you did not split the data before polcal, all the KGB tables will be applied OTF. If you are following methods 1 or 2, you need to fill the xcal model column by setting set_model_pol: True (which is the caracal default). The values for the total intensity and polarization properties are updated with the NRAO web site.

[SpheMakh]

@francescaLoi what's the progress on this?

[francescaLoi]

For me it is ready, I don't know if @o-smirnov wants to add something...