hifa_spwphaseup

hifa_spwphaseup(vis=None, caltable=None, field=None, intent=None, spw=None, hm_spwmapmode=None, maxnarrowbw=None, minfracmaxbw=None, samebb=None, phasesnr=None, intphasesnr=None, intphasesnrmin=None, phaseupmaxsolint=None, bwedgefrac=None, hm_nantennas=None, maxfracflagged=None, combine=None, refant=None, minblperant=None, minsnr=None, unregister_existing=None) → ResultsList[Results][source]

Compute phase calibration spw map and per spw phase offsets.

hifa_spwphaseup computes the spw map for phase calibration, and derives phase offsets as a function of spectral window using high signal-to-noise calibration observations. Previous calibrations are applied on the fly.

hifa_spwphaseup performs two functions:

Logic flowchart for spw phase-up strategy

Logic flowchart for determining the temporal gain strategy. Extends phase-up mapping/combine, solint and gaintype calculation to all intents except the Polarization calibrator.

  • Determines the spectral window mapping or combination mode, gaintype and solint, for each independent bandpass, amplitude, diffgain, phase and check source, to use when solving the phaseup (phase as a function of time) in subsequent stages (mapping mode and gaintype in hifa_gfluxscaleflag, all parameters for hifa_gfluxscale and hifa_timegaincal), and when applying those solutions to targets.

  • Computes the per-spectral-window phase offset table that will be applied to the data to remove mean phase differences between the spectral windows.

If hm_spwmapmode='auto', then the spectral window map is computed for each SpectralSpec and each calibrator source, using the following algorithm:

  • Estimate the per-spectral-window (spw) signal-to-noise ratio based on catalog flux densities, Tsys, number of antennas, and integration scan time. These estimates are shown in the weblog.

  • Compute the per-spw signal-to-noise for each above mentioned intent based on an temporary phaseup gain calibration using solint inf for the PHASE and CHECK intents, and int otherwise. These computed signal-to-noise values override the use of the estimated values unless none are found.

  • If SNR calculation fails, then subsequent heuristics are skipped, warnings printed, and mapping falls back to narrow-to-wide.

  • If the signal-to-noise of all spws is greater than phasesnr for a PHASE or CHECK intent, or greater than intphasesnr for the other intents, then if SNR is high enough to keep solint='int', then no mapping is used (each spw is used to calibrate itself). If the calculated solint is >'int' then mapping and combine are attempted, to favor a short solint over keeping the spws independent.

  • If the signal-to-noise of only some spws are greater than the value of phasesnr for the PHASE or CHECK intent, or intphasesnr for the other intents, then each lower-SNR spw is mapped to the highest SNR spw in the same SpectralSpec.

  • If all spws have low SNR (or all spws in a given SpectraSpec for multi-SpectralSpec observations), then spws are combined.

  • The time solint is calculated and stored for phaseup in subsequent stages. If hm_spwmapmode is not 'combine' then there is at least one high signal-to-noise spw, then by definition that has a solint of 'int'. For hm_spwmapmode='combine', the computed signal-to-noise is used in conjunction with phasesnr for the phase and check intents, or intphasesnr for the other intents. First the gaintype is changed from 'G' to 'T' (combine polarization) and thereafter solint is increased from 'int' up to the limits of 1/2 scan for the phase or check intent, or to the input maxphaseupsolint for the other intents

  • If hm_spwmapmode is 'combine' and no SNRs are found, the PHASE and CHECK intents will default to a solint of 1/4 scan.

  • If the intent is AMPLITUDE, and gaintype was changed from 'G' to 'T', the signal-to-noise required to be met before increasing solint above 'int' is reduced to intphasesnrmin.

If hm_spwmapmode='combine', hifa_spwphaseup maps all the science windows to a single science spectral window. For example, if the list of science spectral windows is [9, 11, 13, 15] then all the science spectral windows in the data will be combined and mapped to the science window 9 in the combined phase vs time calibration table.

If hm_spwmapmode='simple', a mapping from narrow science to wider science spectral windows is computed using the following algorithm:

  • Construct a list of the bandwidths of all the science spectral windows.

  • Determine the maximum bandwidth in this list as maxbandwidth.

  • For each science spectral window with bandwidth less than maxbandwidth, construct a list of spectral windows with bandwidths greater than minfracmaxbw * maxbandwidth, then select the spectral window in this list whose band center most closely matches the band center of the narrow spectral window, and preferentially match within the same baseband if samebb=True.

If hm_spwmapmode='default', the spw mapping is assumed to be one to one.

After determining the combine and mapping parameters and time solints, phase offsets per spectral window are determined by computing a phase only gain calibration on the selected data, normally the high signal-to-noise bandpass calibrator observations, using the solution interval 'inf'.

At the end of the task the spectral window map, solint and gaintype along with the phase offset calibration table(s) in the pipeline are stored in the context for use by later tasks.

Finally, the SNR of the calibration solutions are inspected and if the median value on a per-spw basis does not reach specific thresholds, a warning is issued with a reduced QA score. For PHASE intent, blue, yellow, and red QA result if the achieved SNR is less than 0.75, 0.5, and 0.33 times phasesnr, respectively. For BANDPASS, AMPLITUDE, and DIFFGAIN intent, QA messages are based on 0.75, 0.5, and 0.33 times intphasesnr (unless intphasesnrmin was used for BANDPASS or AMPLITUDE). Finally, for CHECK intent the QA score is always blue, but scales depending on achieved SNR relative to phasesnr.

Phase decoherence assessment

Using the bandpass phase-up solutions from hifa_bandpass, the baseline-based phase RMS is reconstructed for each antenna relative to the reference antenna. For each baseline the phase RMS is calculated over the entire bandpass scan (total-time) and also over a period equal to the phase referencing cycle time. The median phase RMS of all baselines longer than the 80th percentile is reported in the WebLog table.

Outlier antennas (phase RMS > 180 deg, or > 4 x MAD + median when median > 50 deg, or > max(6 x MAD + median, 2 x median) when median <= 50 deg) are identified and shown as semi-transparent symbols in the plot. When outliers are found above 50 deg, a reassessment is made excluding them.

Phase decoherence plots

Example phase decoherence plots (phase RMS vs. baseline length). Semi-transparent points indicate excluded outlier antennas. Horizontal coloured lines show the decoherence thresholds at 30 deg, 50 deg, and 70 deg.

Parameters:

  • vis --

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

    Example: vis=['M82A.ms', 'M82B.ms']

  • caltable --

    The list of output calibration tables. Defaults to the standard pipeline naming convention.

    Example: caltable=['M82.gcal', 'M82B.gcal']

  • field --

    The list of field names or field ids for which phase offset solutions are to be computed. Defaults to all fields with the default intent.

    Example: field='3C279', field='3C279, M82'

  • intent --

    A string containing a comma delimited list of intents against which the selected fields are matched. Defaults to the BANDPASS observations.

    Example: intent='PHASE'

  • spw --

    The list of spectral windows and channels for which gain solutions are computed. Defaults to all the science spectral windows.

    Example: spw='13,15'

  • hm_spwmapmode --

    The spectral window mapping mode. The options are: 'auto', 'combine', 'simple', and 'default'. In 'auto' mode hifa_spwphaseup estimates the SNR of the phase calibrator observations and uses these estimates to choose between 'combine' mode (low SNR) and 'default' mode (high SNR). In combine mode all spectral windows are combined and mapped to one spectral window. In 'simple' mode narrow spectral windows are mapped to wider ones using an algorithm defined by 'maxnarrowbw', 'minfracmaxbw', and 'samebb'. In 'default' mode the spectral window map defaults to the standard one to one mapping.

    Example:`` hm_spwmapmode='combine'``

  • maxnarrowbw --

    The maximum bandwidth defining narrow spectral windows. Values must be in CASA compatible frequency units.

    Example: maxnarrowbw=''

  • minfracmaxbw --

    The minimum fraction of the maximum bandwidth in the set of spws to use for matching.

    Example: minfracmaxbw=0.75

  • samebb --

    Match within the same baseband if possible.

    Example: samebb=False

  • phasesnr --

    The required phase gaincal solution signal-to-noise.

    Example: phasesnr=20.0

  • intphasesnr --

    The required solint='int' phase gaincal solution signal-to-noise.

    Example: intphasesnr=4.0

  • intphasesnrmin --

    The required solint='int' phase gaincal solution signal-to-noise for fields that cover the AMPLITUDE calibrator intent.

    Example: intphasesnrmin=3.0

  • phaseupmaxsolint --

    Maximum phase correction solution interval (in seconds) allowed in very low-SNR cases. Used only when hm_spwmapmode = 'auto' or 'combine'.

    Example: phaseupmaxsolint=60.0

  • bwedgefrac --

    The fraction of the bandwidth edges that is flagged.

    Example: bwedgefrac=0.0

  • hm_nantennas --

    The heuristics for determines the number of antennas to use in the signal-to-noise estimate. The options are 'all' and 'unflagged'. The 'unflagged' options is not currently supported.

    Example: hm_nantennas='unflagged'

  • maxfracflagged --

    The maximum fraction of an antenna that can be flagged before it is excluded from the signal-to-noise estimate.

    Example: maxfracflagged=0.80

  • combine --

    Data axes to combine for solving. Options are '', 'scan', 'spw', 'field' or any comma-separated combination.

    Example: combine=''

  • refant --

    Reference antenna name(s) in priority order. Defaults to most recent values set in the pipeline context. If no reference antenna is defined in the pipeline context the CASA defaults are used.

    Example: refant='DV01', refant='DV05,DV07'

  • minblperant --

    Minimum number of baselines required per antenna for each solve. Antennas with fewer baselines are excluded from solutions.

    Example: minblperant=2

  • minsnr -- Solutions below this SNR are rejected.

  • unregister_existing -- Unregister previous spwphaseup calibrations from the pipeline context before registering the new calibrations from this task.

Notes

QA scores for phase decoherence:

  • Phase RMS < 30 deg (excellent stability): QA = 1.0 (or 0.9 if outlier antennas detected).

  • Phase RMS 30-50 deg (good stability): QA = 0.9.

  • Phase RMS 50-70 deg (notably elevated): QA between 0.3 and 0.5.

  • Phase RMS > 70 deg (poor stability): QA between 0.0 and 0.3.

Phase RMS of 30 deg, 50 deg, and 70 deg correspond to flux decoherence of ~13%, ~32%, and ~53% respectively. These thresholds are shown as coloured horizontal lines in the phase decoherence plots.

The overall stage score is the lowest of the gain calibration QA and the phase decoherence QA.

Returns:

The results object for the pipeline task is returned.

Examples

  1. Compute the default spectral window map and the per spectral window phase offsets:

>>> hifa_spwphaseup()

2. Compute the default spectral window map and the per spectral window phase offsets set the spectral window mapping mode to 'combine':

>>> hifa_spwphaseup(hm_spwmapmode='combine')