hifa_diffgaincal

hifa_diffgaincal(vis=None, flagging_frac_limit=None, hm_spwmapmode=None, missing_scans_frac_limit=None) → ResultsList[DiffGaincalResults][source]

Derive SpW phase offsets from differential gain calibrator.

This task creates the spectral window phase offset table used to allow calibrating the "on-source" spectral setup with phase gains from a "reference" spectral setup. Currently this setup with two different SpectralSpecs is used by the band-to-band mode, for a high and low frequency band.

A bright point source quasar, called the Differential Gain Calibrator (DIFFGAIN) source, is used for this purpose. This DIFFGAIN source is typically observed in groups of interleaved "reference" and "on-source" scans. These blocks typically occur once at the start and once at the end of the observation. In very long observations, there may be a group of scans occurring during the middle.

The procedure for the phase calibration process is as follow:

  • reference calibration uses the "reference" spectral setup, the "low" frequency for band-to-band observations. The solint is fixed as 'inf' (i.e. solutions are made per scan). Spectral window combination is governed by the hm_spwmapmode options described below. In standard pipeline operation auto is used - basing spw combination upon SNR and flagging level. These reference phase solutions are later applied on-the-fly while solving the (band-to-band) phase offset. The premise being that the reference solutions correct for atmospheric phase variability.

  • phase offset (i.e. the band-to-band correction) calibration uses the "on-source" spectral setup, the "high" frequency for band-to-band observations. The above reference phase corrections are applied on-the-fly using a linearPD interpolation - this corrects (scales) the phases according to the different ratio of the frequency bands. The solint = 'inf' and each group of scan blocks (typically at the start and end of the observation) are combined respectively. The phase offset solution generally comprises of 2 time solutions per spw, per polarization. Spectral window combination is governed by the hm_spwmapmode options described below. auto is used - basing spw combination upon SNR and flag data. These solutions are stored in the pipeline context for later application to the TARGET and CHECK intent(s).

  • residual offset solutions are produced by applying both reference and band-to-band phase offset solutions to the 'on-source' DIFFGAIN intent on-the-fly, and subsequently solving phases per spw, per scan using solint='inf'. Spectral window combination is governed by the hm_spwmapmode options described below. auto is used - basing spw combination upon SNR and flagging level.

Residual solutions pre-apply all corrections and solve for the scan-based DIFFGAINSRC phases. These are designed to scatter about zero degrees with no drift. Residuals not limited by SNR should ideally be within +/-30 deg; good-conditions data should be within +/-50 deg.

As of PL2025, low-SNR heuristics allow combine='spw' to be used in any of the three solve steps. The heuristic is triggered if (i) combine='spw' was required in hifa_spwphaseup for the DIFFGAIN intent, or (ii) a temporary gaincal shows that the fraction of flagged or missing solutions would exceed 0.7 of the total.

Gain solution workflow for hifa_diffgaincal

Left: gain solution workflow with low-SNR heuristic before each gaincal. Right: low-SNR heuristic logic for spectral window combination.

Parameters:

  • vis --

    The list of input MeasurementSets. Defaults to the list of MeasurementSets specified in the pipeline context.

    Example: ['M32A.ms', 'M32B.ms']

  • flagging_frac_limit -- if the fraction of flagged data in the temporary phase gaintable exceeds this limit then SpW combination is triggered.

  • hm_spwmapmode --

    The spectral window mapping heuristic mode. The options are:

    • 'all': SpW combination is forced for the diffgain

      low-frequency reference intent solutions, the diffgain high-frequency source intent solutions (actual band-to-band offsets), and for the diagnostic residual phase offsets on the diffgain high-frequency source intent.

    • 'auto': Assess need for SpW combination based on SpwMapping

      from hifa_spwphaseup, and where necessary check the gaintable for missing SpWs / too many flagged data / too few scan solutions.

    • 'both': SpW combination is forced for the diffgain

      low-frequency reference intent solutions and for the diagnostic residual phase offsets on the diffgain high-frequency source intent.

    • 'offset': SpW combination is forced for the diffgain

      high-frequency source intent solutions (actual band-to-band offsets).

    • 'reference': SpW combination is forced for the diffgain

      low-frequency reference intent solutions.

    • 'residual': SpW combination is forced for the diagnostic

      residual phase offsets on the diffgain high-frequency source intent.

    Example: hm_spwmapmode='auto'

  • missing_scans_frac_limit -- if the fraction of missing scans in the temporary phase gaintable exceeds this limit then SpW combination is triggered.

Notes

QA sub-scores:

  • 1.0 if each caltable (reference, band-to-band offset, residual) is successfully produced; 0.0 if any table is missing (which invalidates the calibration).

  • 0.9 (informative only) if combine='spw' was required for any of the three solve steps; 1.0 otherwise.

Only used in band-to-band (diffgain) recipes.

Returns:

The results object for the pipeline task is returned.

Examples

  1. Derive SpW phase offsets from differential gain calibrator.

>>> hifa_diffgaincal()