hif_selfcal

hif_selfcal(vis=None, field=None, spw=None, contfile=None, hm_imsize=None, hm_cell=None, apply=None, recal=None, restore_only=None, overwrite=None, refantignore=None, restore_resources=None, n_solints=None, amplitude_selfcal=None, gaincal_minsnr=None, minsnr_to_proceed=None, delta_beam_thresh=None, apply_cal_mode_default=None, rel_thresh_scaling=None, dividing_factor=None, check_all_spws=None, inf_EB_gaincal_combine=None, usermask=None, usermodel=None, allow_wproject=None, parallel=None) → Results[source]

Perform iterative self-calibration on science targets with sufficient signal.

Attempts phase-only self-calibration on each science target for which the estimated SNR per-EB per-antenna exceeds 3. The task channels-averages the science data to 15.625 MHz, flags line channels (from hif_findcont), splits each source into a temporary MS, and then iterates through a series of gain solution intervals.

The pipeline tracks multiple data type labels to manage regular and self-calibrated data:

  • REGCAL_CONTLINE_SCIENCE: data with regular calibrations applied (DATA column of *_targets.ms).

  • SELFCAL_CONTLINE_SCIENCE: data with self-calibration solutions applied (CORRECTED column of *_targets.ms).

  • REGCAL_LINE_SCIENCE / SELFCAL_LINE_SCIENCE: equivalent line (continuum-subtracted) datatypes in *_targets_line.ms.

Solution interval sequence: The first interval is always inf_EB (combine='scan', solint='inf', gaintype='G'), covering one entire EB and initially solving per-spw, per-polarization. Subsequent intervals use combine='spw', gaintype='T': inf (one solution per scan), intermediate intervals splitting the median scan time, and finally int (one solution per integration). The target is 5 total intervals including inf and int. Only the final successful interval and inf_EB (if not the final) are applied; intermediate successful intervals are discarded.

Solution acceptance: A solution interval is accepted if all of the following hold:

  • The synthesized beam area does not increase by more than 5% compared with the pre-selfcal image.

  • The SNR of the post-selfcal image exceeds the SNR of the pre-selfcal image.

  • The near-field SNR (rms measured in an annulus just outside the clean mask) also improves.

  • The rms does not increase by more than 5%.

If self-calibration succeeds, results are applied to both *_targets.ms and *_targets_line.ms. The final image is cleaned to the minimum of 3 x rms (from the final successful interval) and the pre-selfcal clean threshold.

The WebLog shows a summary table of solution intervals attempted, SNR/rms before and after each interval, and whether self-calibration succeeded. Per-interval QA plot pages show before/after images and gain solutions per EB and antenna.

Self-calibration WebLog

Example WebLog. The 'List of Self-cal Targets' table shows targets, imaging parameters, solution intervals, and success status. The 'Self-cal Target Details' section shows before/after SNR, rms, beam size, and images, and describes why self-calibration stopped.

Parameters:

  • vis -- The list of input MeasurementSets. Defaults to the list of MeasurementSets defined in the pipeline context.

  • field -- Select field(s) for self-calibration. Use field name(s) NOT id(s). Mosaics are assumed to have common source/field names.

  • spw -- Select spectral windows for self-calibration.

  • contfile -- Name of file to specify line-free frequency ranges for selfcal continuum imaging. Defaults to 'cont.dat'.

  • hm_imsize -- self-calibration imaging dimension in pixels, or PB level for single fields.

  • hm_cell -- self-calibration imaging cell size.

  • apply -- Apply final selfcal solutions back to the input MeasurementSets. Defaults to True.

  • recal --

    Always re-do self-calibration even solutions/caltables are found in the Pipeline context or json restore file. Defaults to False.

    Note that the selfcal solutions might not be applied if self-calibrated data labeled by the pipeline Datatypes already exists. See overwrite below.

  • restore_only -- Only attempt to apply pre-existing selfcal calibration tables and would not run the self-calibration sequence if their records (.selfcal.json, gaintables) are not present. Defaults to False. restore_only will take precedence over recal.

  • overwrite -- Allow overwriting pre-existing self-calibrated data of applicable field/spw labeled by DataType. Defaults to False.

  • refantignore --

    Antennas to be ignored as reference antennas. Defaults to ''. Examples:

    • refantignore='ea02,ea03'

    • refantignore={'ms1.ms':'ea02,ea03','ms2.ms': 'ea03'}, specified at the per-ms level.

  • restore_resources -- Path to the restore resources from a standard run of hif_selfcal. hif_selfcal will automatically do an exhaustive search to lookup/extract/verify the selfcal restore resources, i.e., selfcal.json and all selfcal-caltable referred in selfcal.json, starting from working/, to products/ and rawdata/. If restore_resources is specified, this file path will be evaluated first before the pre-defined exhaustive search list. The value can be the file path of *auxproducts.tgz file or *selfcal.json file.

  • n_solints -- number of solution intervals to attempt for self-calibration. Defaults to 4.

  • amplitude_selfcal -- Attempt amplitude self-calibration following phase-only self-calibration; if median time between scans of a given target is < 150s, solution intervals of 300s and inf will be attempted, otherwise just inf will be attempted. Defaults to False.

  • gaincal_minsnr -- Minimum S/N for a solution to not be flagged by gaincal. Defaults to 2.0.

  • minsnr_to_proceed -- Minimum estimated S/N on a per antenna basis to attempt self-calibration of a source. Defaults to 3.0.

  • delta_beam_thresh -- Allowed fractional change in beam size for selfcalibration to accept results of a solution interval. Defaults to 0.05.

  • apply_cal_mode_default -- Apply mode to use for applycal task during self-calibration; same options as applycal. Defaults to 'calflag'.

  • rel_thresh_scaling -- Scaling type to determine how clean thresholds per solution interval should be determined going from the starting clean threshold to 3.0 * RMS for the final solution interval. Defaults to 'log10'. Available options: 'linear', 'log10', or 'loge' (natural log)

  • dividing_factor -- Scaling factor to determine clean threshold for first self-calibration solution interval. Equivalent to (Peak S/N / dividing_factor) * RMS as the first clean threshold; however, if (Peak S/N / dividing_factor) < 5.0; a value of 5.0 is used for the first clean threshold. Defaults to 40 for < 8 GHz or 15 for > 8 GHz.

  • check_all_spws -- If True, the S/N of mfs images created on a per-spectral-window basis will be compared at the initial stages final self-calibration. Defaults to False.

  • inf_EB_gaincal_combine -- change gain solution combination parameters for the inf_EB solution interval. if True, the gaincal combine parameter will be set to 'scan,spw'; if False, the gaincal combine parameter will be set to 'scan'. Defaults to False.

  • usermask -- User mask to be used for self-calibration imaging. (not implemented)

  • usermodel -- User model to be used for self-calibration imaging. (not implemented)

  • allow_wproject -- Allow the wproject heuristics for self-calibration imaging. Defaults to False.

  • parallel --

    Process multiple MeasurementSets in parallel using the casampi parallelization framework, and use CASA/tclean parallel imaging, when possible.

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

    Default: None (equivalent to `'automatic')

Notes

QA scores:

  • QA = 1.0 if self-calibration was not attempted (SNR too low).

  • QA = 0.99 if attempted but unsuccessful (solutions not applied).

  • QA = 0.98 if attempted and applied successfully.

  • QA = 0.85 if applied but the RMS got worse for at least one source.

  • QA = 0.90 if a new/experimental mode (e.g. mosaic self-calibration) was used.

  • QA = N/A for unsupported modes (e.g. ephemeris targets).

Returns:

The results object for the pipeline task is returned.

Examples

  1. Run self-calibration on all science targets:

>>> hif_selfcal()

  1. Run self-calibration on a single science target:

>>> hif_selfcal(field='3C279')

  1. Use a more relaxed beam-size acceptance threshold:

>>> hif_selfcal(delta_beam_thresh=0.15)