hifa_bandpass

hifa_bandpass(vis=None, caltable=None, field=None, intent=None, spw=None, antenna=None, hm_phaseup=None, phaseupbw=None, phaseupmaxsolint=None, phaseupsolint=None, phaseupsnr=None, phaseupnsols=None, hm_phaseup_combine=None, hm_bandpass=None, solint=None, maxchannels=None, evenbpints=None, bpsnr=None, minbpsnr=None, bpnsols=None, combine=None, refant=None, solnorm=None, minblperant=None, minsnr=None, unregister_existing=None, hm_auto_fillgaps=None, parallel=None) → ResultsList[Results][source]

Performs temporal phase-up and derives bandpass calibration solutions.

This task self-calibrates the bandpass calibrator by first obtaining phase-only solutions on a short time interval determined by signal-to-noise. It then calculates the antenna-based bandpass phase and amplitude solutions using an SNR-dependent frequency interval.

Parameters:

  • vis --

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

    Example: vis=['ngc5921.ms']

  • caltable --

    List of names for the output calibration tables. Defaults to the standard pipeline naming convention.

    Example: caltable=['ngc5921.gcal']

  • field --

    The list of field names or field ids for which bandpasses are computed. Set to field='' by default, which means the task will select all fields.

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

  • intent --

    A string containing a comma delimited list of intents against which the selected fields are matched. Set to intent='' by default, which means the task will select all data with the BANDPASS intent.

    Example: intent='*PHASE*'

  • spw --

    The list of spectral windows and channels for which bandpasses are computed. Set to spw='' by default, which means the task will select all science spectral windows.

    Example: spw='11,13,15,17'

  • antenna -- Set of data selection antenna IDs

  • hm_phaseup --

    The pre-bandpass solution phaseup gain heuristics. The options are:

    • 'snr': compute solution required to achieve the specified SNR

    • 'manual': use manual solution parameters

    • '': skip phaseup

    Example: hm_phaseup='manual'

  • phaseupbw --

    Bandwidth to be used for phaseup. Used when hm_phaseup= 'manual'.

    Example:

    • phaseupbw='' to use entire bandpass

    • phaseupbw='500MHz' to use central 500MHz

  • phaseupmaxsolint --

    Maximum phase correction solution interval (in seconds) allowed in very low-SNR cases. Used only when hm_phaseup='snr'. Note that in limiting cases, the interval can slightly exceed this value as an integer number of integrations must be used (e.g., if integration time is 6.048s, ten integrations is 60.48s).

    Example: phaseupmaxsolint=60.0

  • phaseupsolint --

    The phase correction solution interval in CASA syntax. Used when hm_phaseup='manual' or as a default if the hm_phaseup='snr' heuristic computation fails.

    Example: phaseupsolint='300s'

  • phaseupsnr --

    The target signal-to-noise ratio for the temporal phase-up. Used to calculate the phaseup time solint, and only if hm_phaseup='snr'.

    Example: phaseupsnr=10.0

  • phaseupnsols --

    The minimum number of phaseup gain solutions. Used only if hm_phaseup='snr'.

    Example: phaseupnsols=4

  • hm_phaseup_combine --

    The spw combination heuristic for the phase-up solution. Accepts one of following 3 options:

    • 'snr', default: heuristics will use combine='spw' in phase-up gaincal, when SpWs have SNR < phaseupsnr (default = 20).

    • 'always': heuristic will force combine='spw' in the phase-up gaincal.

    • 'never': heuristic will not use spw combination; this was the default logic for Pipeline release 2024 and prior.

    Example: hm_phaseup_combine='always'

  • hm_bandpass --

    The bandpass solution heuristics. The options are: 'snr': compute the solution required to achieve the specified SNR 'smoothed': simple 'smoothing' i.e. spectral solint>1chan 'fixed': use the user defined parameters for all spws

    Example: hm_bandpass='snr'

  • solint --

    The solution interval for the gain calibration. The value is computed based on achieving the phaseupsnr for all spectral windows (spws). It is increased incrementally in units of the integration time up to phaseupmaxsolint. Defaults to 'int'.

    Example: solint='int'

  • maxchannels --

    The bandpass solution 'smoothing' factor in channels, i.e. spectral solint will be set to bandwidth / maxchannels Set to 0 for no smoothing. Used if hm_bandpass='smoothed'.

    Example: maxchannels=240

  • evenbpints --

    Force the per spw frequency solint to be evenly divisible into the spw bandpass if hm_bandpass='snr'.

    Example: evenbpints=False

  • bpsnr --

    The required SNR for the bandpass solution. Used only if hm_bandpass='snr'.

    Example: bpsnr=30.0

  • minbpsnr --

    The minimum required SNR for the bandpass solution when strong atmospheric lines exist in Tsys spectra. Used only if hm_bandpass='snr'.

    Example: minbpsnr=10.0

  • bpnsols --

    The minimum number of bandpass solutions. Used only if hm_bandpass= 'snr'.

    Example: bpnsols=8

  • combine --

    The combine parameter for the CASA bandpass task. If solint is not 'int', this is changed from the default 'scan' to 'scan,spw' to combine all spws, improving the SNR.

    Example: combine='scan,field'

  • refant --

    List of reference antenna names. Defaults to the value(s) stored in the pipeline context. If undefined in the pipeline context defaults to the CASA reference antenna naming scheme.

    Example: refant='DV06,DV07'

  • solnorm --

    Normalise the bandpass solution; defaults to True.

    Example: solnorm=False

  • minblperant --

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

    Example: minblperant=4

  • minsnr --

    Solutions below this SNR are rejected in the phaseup and bandpass solves.

    Example: minsnr=3.0

  • unregister_existing --

    Unregister all bandpass calibrations from the pipeline context before registering the new bandpass calibrations from this task. Defaults to False.

    Example: unregister_existing=True

  • hm_auto_fillgaps -- If True, sets the fillgaps parameter of the underlying CASA bandpass task to 1/4 of each spw width. This allows interpolation across celestial spectral features in the bandpass calibrator spectrum and avoids gaps due to strong atmospheric lines. Defaults to True in calibration recipes.

  • parallel --

    Process multiple MeasurementSets in parallel using the casampi parallelization framework.

    Options: 'automatic', 'true', 'false', True, False

    Default: None (equivalent to False)

Notes

Temporal Phase-Up Workflow

As of PL2025, the solint and combine options are computed to achieve the target phaseupsnr. If solint is not 'int', the combine parameter is set to 'scan,spw' to combine data from all spectral windows, thereby improving SNR. In this case, a temporary gaincal solution is made to obtain per-spw phase-offsets to align the phases of all spws. The solint is then calculated based on the SNR for the aggregate bandwidth.

The logical workflow is illustrated below:

Workflow for hifa_bandpass temporal phase-up

The logical workflow for the temporal phase-up process used in the hifa_bandpassflag and hifa_bandpass tasks that compute the gaincal solint and combine parameters.

Frequency Interval Calculation

The frequency interval for the final bandpass solution is determined by SNR. Since PL2024, this interval is rounded to counteract the floor() function in CASA, ensuring the interval has the desired number of channels. If the interval needed to reach the required SNR results in fewer than 8 channels, the interval is set to one-eighth of the bandwidth, and the result is assigned a QA subscore of 0.70.

WebLog Output and QA Metrics

The WebLog for this stage includes plots of amplitude and phase vs. frequency for the reference and a typical antenna, with the atmospheric transmission curve overlaid. QA metrics are calculated as follows:

  • Amplitude SNR Metric: An error function with a 1-sigma deviation of 1.0 for the amplitude signal-to-noise ratio.

  • Phase Derivative Deviation (DD) Metric: An error function with a 1-sigma deviation of 0.03 for the "outlier fraction" (fraction of channels with a phase change > 5 MAD). This is mapped to a linear score:

    • 0.34 - 0.66 for DD < 0.2 (>12% outliers)

    • 0.67 - 0.9 for DD between 0.2 - 0.3

    • 0.91 - 1.0 for DD >= 0.3 (<8% outliers)

  • A QA sub-score of 0.9 is assigned if spws were combined in the phase-up step (from PL2025).

BLC FDM Subband QA (PL2025+)

For data from FDM spectral windows using the Baseline Correlator (BLC), a new QA assesses anomalous features (e.g., offsets, jumps) at subband edges (effective width 58.59375 MHz). The score is based on five heuristics (two for phase, three for amplitude) per spw, antenna, and polarization that check for noisy subbands, offsets between subbands, and large amplitude spikes.

  • If any heuristic is triggered, the QA score is between 0.35 and 0.65, based on the fraction of the affected spw.

  • The evaluation is skipped and a score of 0.70 is assigned if an spw is narrow (< 125 MHz) or if low SNR requires a frequency interval >= the subband width.

  • If no issues are found or the data is not BLC FDM, the score is 1.0.

Returns:

The results object for the pipeline task is returned.

Examples

  1. Run with recommended settings:

>>> hifa_bandpass()