hifa_gfluxscale

hifa_gfluxscale(vis=None, reference=None, transfer=None, refintent=None, transintent=None, refspwmap=None, reffile=None, phaseupsolint=None, solint=None, minsnr=None, refant=None, hm_resolvedcals=None, antenna=None, peak_fraction=None, amp_outlier_sigma=None, parallel=None) → ResultsList[Results][source]

Transfer the absolute flux scale from amplitude calibrator to secondary calibrators and science targets.

Derives flux densities for point-source transfer calibrators using flux models for reference calibrators. The absolute flux scale is transferred from the amplitude calibrator to the phase calibrator and other secondary calibrators, which is subsequently transferred to the science target via hif_applycal.

The workflow (as illustrated in the WebLog logic diagram):

Logical flow in hifa_gfluxscale

Logical flow in hifa_gfluxscale. Each box represents one gaincal call per intent/field/Spectral Spec/EB. Italicized parameters originate from hifa_spwphaseup.

  1. Phase-up calibration is performed for all science spws for each calibrator field using the spw mapping/combine parameters and solint/gaintype established in hifa_spwphaseup.

  2. Amplitude-only solutions are computed (with gaintype='T', combining polarisations), pre-applying the phase solutions.

  3. Obvious outlier amplitude solutions are identified and flagged in the caltable.

  4. The flux scale is transferred from the reference calibrators to the transfer calibrators using refspwmap for windows without data in the reference calibrators.

  5. The computed flux density values are written to the MODEL_DATA column via setjy.

The WebLog lists the derived flux scale factors and calibrated flux densities (measured by vector-averaged calibrated visibility amplitude) for all non-amplitude calibrators, together with the ALMA Source Catalog values. Plots of amplitude vs. uv distance are shown.

Limited uv ranges for resolved calibrators

Example of limited uv ranges for deriving the flux scale on resolved solar system objects.

Derived vs. catalog flux density plot

Examples of derived vs. catalog flux density plots and associated QA messages.

Resolved calibrator antenna selection: If the amplitude calibrator is resolved (i.e., it shows decreasing flux with increasing uv distance, which is assumed to apply only to solar system objects), only short baseline antennas are used in the calibration solves. The selection algorithm is:

  1. Estimate the solar system object calibrator size.

  2. Determine the longest observing wavelength across the science spws.

  3. Determine the shortest unprojected baseline to the reference antenna.

  4. Estimate the peak visibility amplitude at that baseline length.

  5. Find the baseline length where the transform of a uniform disk drops to 20% of that peak.

  6. Select antennas whose separation from the refant is within that length.

  7. If fewer than 3 antennas qualify, default to using all antennas.

The selected antennas are listed in the WebLog table (blank entries mean all antennas were used, as is the case for quasar calibrators). The antenna selection can also be set manually via hm_resolvedcals and antenna parameters.

Parameters:

  • vis --

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

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

  • reference --

    A string containing a comma delimited list of field names defining the reference calibrators. Defaults to names of fields with intents in refintent.

    Example: reference='M82,3C273'

  • transfer --

    A string containing a comma delimited list of field names defining the transfer calibrators. Defaults to names of fields with intents in transintent.

    Example: transfer='J1328+041,J1206+30'

  • refintent --

    A string containing a comma delimited list of intents used to select the reference calibrators. Defaults to 'AMPLITUDE'.

    Example: refintent='', r``efintent='AMPLITUDE'``

  • transintent --

    A string containing a comma delimited list of intents defining the transfer calibrators. Defaults to 'PHASE,BANDPASS,CHECK,DIFFGAINREF,DIFFGAINSRC,POLARIZATION,POLANGLE,POLLEAKAGE'.

    Example: transintent='', transintent='PHASE,BANDPASS'

  • refspwmap --

    Vector of spectral window ids enabling scaling across spectral windows. Defaults to no scaling.

    Example: refspwmap=[1,1,3,3] - (4 spws, reference fields in 1 and 3, transfer fields in 0,1,2,3)

  • reffile --

    Path to a file containing flux densities for calibrators. Setjy will be run for any that have both reference and transfer intents. Values given in this file will take precedence over MODEL column values set by previous tasks. By default, the path is set to the CSV file created by hifa_importdata, consisting of catalogue fluxes extracted from the ASDM and / or edited by the user.

    Example: reffile='', reffile='working/flux.csv'

  • phaseupsolint --

    Time solution intervals in CASA syntax for the phase solution.

    Example: phaseupsolint='inf', phaseupsolint='int', phaseupsolint='100sec'

  • solint --

    Time solution intervals in CASA syntax for the amplitude solution.

    Example: solint='inf', solint='int', solint='100sec'

  • minsnr --

    Minimum signal-to-noise ratio for gain calibration solutions.

    Example: minsnr=1.5, minsnr=0.0

  • refant --

    A string specifying the reference antenna(s). By default, this is read from the context.

    Example: refant='DV05'

  • hm_resolvedcals -- Heuristics method for handling resolved calibrators. The options are 'automatic' and 'manual'. In automatic mode, antennas closer to the reference antenna than the uv distance where visibilities fall to peak_fraction of the peak are used. In manual mode, the antennas specified in antenna are used.

  • antenna --

    A comma delimited string specifying the antenna names or ids to be used for the fluxscale determination. Used in hm_resolvedcals='manual' mode.

    Example: antenna='DV16,DV07,DA12,DA08'

  • peak_fraction -- The limiting UV distance from the reference antenna for antennas to be included in the flux calibration. Defined as the point where the calibrator visibilities have fallen to peak_fraction of the peak value.

  • amp_outlier_sigma --

    Sigma threshold used to identify outliers in the amplitude caltable. Default: 50.0.

    Example: amp_outlier_sigma=30.0

  • parallel --

    Process multiple MeasurementSets in parallel using the casampi parallelization framework.

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

    Default: None (equivalent to False)

Notes

Three QA scores are computed for all non-FLUX calibrators:

  1. Completeness: fraction of spws with a derived flux determination (1.0 if all spws have a value, 0.5 if only half do, etc.).

  2. SNR: QA is blue (warning) if the flux determination SNR falls below 20, yellow (fail) if below 5, with linear interpolation between these limits.

  3. Spectral consistency: compares derived spectral index across spws to the Source Catalog. For each spw, R_spw = derived / catalog flux; K_spw = R_spw / R_spw(highest-SNR spw). QA score is based on max(|1 - K_spw|):

    • QA = 1.0 if max deviation < 0.1

    • QA = 0.75 if max deviation 0.1-0.2

    • QA = 0.5 if max deviation > 0.2

The spectral consistency score can be low for reasons unrelated to the flux scale (e.g., low SNR in some spws causing amplitude noise bias, or atmospheric absorption lines). Check hif_applycal to determine whether any low score represents a real science target issue.

For very low SNR, the longer solint used in the phase-up can cause phase decoherence to be 'baked in', artificially biasing amplitude gains upward and producing an incorrect flux scale.

Returns:

The results object for the pipeline task is returned.

Examples

  1. Compute flux values for the phase calibrator using model data from the amplitude calibrator:

>>> hifa_gfluxscale()