Sky-model calibration¶

Caution

Sky-model calibration is still a work in progress and should not be relied upon. It uses an idealised primary beam response (i.e. no holography) when predicting the apparent brightness of sources towards a direction. This level of of precision may not be suited for some purposes (e.g. bandpass calibration).

flint provides basic functionality that attempts to create a sky-model that could be used to calibrate against. By using a reference catalogue that describes the positions of a set of 2D Gaussian components, their shape and spectral variance, the sky as the telescope sees it can be predicted. The subsequent model, provided the estimation is correct, can then be used to to predict model visibilities and perform subsequent calibration.

This functionality was the genesis of the flint codebase, but it has not been incorporated into any of the calibration workflow procedures. It outputs a text file based on the name of the input measurement set and specified desired output format. That is to say it does not produce predicted model visibilities in of itself, but ddepending on context can be provided to something that could predict and/or solve.

Basic Overview¶

There are three principle components that are required to create a local sky-model:

1 - A basic catalogue at a known frequency. Where possible it should also describe the intrinsic spectral behaviour of each source component, 2 - The desired frequency and direction of the sky where the model is being estimated, and 3 - A ddescription of the primary beam of the instrument.

flint integrated functionality to interact with a set of known referencce catalogues. These catalogues describe the sky as a set of two-dimensional Gaussian components at a particular frequency. The apparent brightness of components in a nominated reference catalogue are estimated by extracting the frequency and pointing direction information encoded in a measurement set and estimating the primary beam direction. flint)currently supports gaussian, sincsquared and airy type responses.

Once the apparent brightness of a source is estimated across all nominated frequencies (extracted from an input measurement set) flint will fit a low-order polynomial model to the resulting spectra. The constrained modeel parameters are subsequently encoded in the output models. Model visibilities can then be produced and insertede as a MODEL_DATA column in the nominated measurement set for subsequent calibration.

Caution

Although there are three response patterns known (Gaussian, SincSquared and Airy) only the Gaussian response is used when creating the sky-model through flint.sky_model.create_sky_model.

Fitting the spectral shape¶

flint will fit a third order polynomial in log space when constrain the apparent spectrum.

The exact functional form is presented below:

def curved_power_law(
    nu: np.ndarray, norm: float, alpha: float, beta: float, ref_nu: float
) -> np.ndarray:
    """A curved power law model.

    >>> S_nu = S_nu_0 * (nu/nu_0)**alpha * exp(beta*ln(nu/nu_0)**2.)

    Note that in the case of beta=0. the model reduces to a normal power-law.

    Args:
        nu (np.ndarray): Frequency array.
        norm (float): Reference flux.
        alpha (float): Spectral index.
        beta (float): Spectral curvature.
        ref_nu (float): Reference frequency.

    Returns:
        np.ndarray: Model flux.
    """
    x = nu / ref_nu
    c = np.exp(beta * np.log(x) ** 2)

    return norm * x**alpha * c

Holography is not currently suupported¶

The ASKAP observatory performs regular holography measurements to characterise the primary beam response of each of the electonically formed beams. The output response pattern is known to now be entirely consistent with analytical descriptions of idealised beam responses. Presently flint does not use the holography to estimate the apparent brightness of sources.

Therefore it may be unwise to use such a sky-model as the basis of bandpass calibration. In time this type of prediction may be inforporated into flint, but presently it remains as a future to-do. Contributions are welcome.

Output model types¶

flint will write out the local sky model in a variety of formats.

`calibrate` and `wsclean --save-source-list` style¶

This is a self-descriptive format format that supports point sources and two-dimensional Gaussians. This format is also known as the BBS style.

Positions are in the J2000 epoch. The nominal frequenci is encoded in Hz as part of the ReferenceFrequency column title. Fluxes are recorded in Jy. Major and minor axis sizes of Gaussian components are in units of arcsecond, with the PA in degrees.

The nominal intensity column I is measured at the reference frequency. A list polynomial co-efficients in logarithmic space may be provided in the SpectralIndex column.

This file format is what wsclean produces via its --save-source-list option. Below is an example of the header and first row of the sky-model. This style of sky-model may be used as an input for crystalball and addmodel, as described in the subtract cube imaging workflow.

Format = Name, Type, Ra, Dec, I, SpectralIndex, LogarithmicSI, ReferenceFrequency='743990740.7407408', MajorAxis, MinorAxis, Orientation
174748-312315,GAUSSIAN,17:47:48.619992,-31.23.15.20016,0.19411106571231185,[-3.806350913533059,-4.135453173684361],true,743990740.7407408,68.5999984741211,68.5999984741211,59.79999923706055,

A more thorough and complete version of this BBS style format may be accessed here.

`hyperdrive` style¶

hyperdrive is extremely efficient calibration utility developed for the MWA. Although ASKAP is obviously not MWA, under some conditions it is possibly to use hyperdrive to calibrate ASKAP measurement sets. There are some technical considerations that sometimes prohibit this, but when it works it is extremely speedy.

There are a number of formats that hyperdrive supports when specifying a sky-model. In flint we choose to output sources in a yaml style format, when each component is described as a record in a fairly flat schema. See their description page for more information.

Below is an example of how to describe a single source.

174748-312315:
- comp_type:
    gaussian:
      maj: 68.5999984741211
      min: 18.5
      pa: 59.79999923706055
  dec: -31.3875556
  flux_type:
    curved_power_law:
      fd:
        freq: 743990740.7407408
        i: 0.19411106571231185
      q: -4.135453173684361
      si: -3.806350913533059
  ra: 266.9525833

DS9 region file¶

flint may also be configured to output a simple DS9 region file that can be used as an overlauf. Of course, no brightness information is recorded, and we refer the reader to DS9 documentation for more information on the region style format.

The first source is listed as an example.

# DS9 region file
fk5
ellipse(266.952583,-31.387556,68.599998,18.500000,149.800003) # color=red dash=1

Accessing via the CLI¶

The primary entry point for the skymodel program in flint is the flint_skymodel:

Create a calibrate compatible sky-model for a given measurement set.

usage: flint_skymodel [-h] [--holofile HOLOFILE]
                      [--reference-catalogue-directory REFERENCE_CATALOGUE_DIRECTORY]
                      [--reference-name REFERENCE_NAME]
                      [--assumed-alpha ASSUMED_ALPHA]
                      [--assumed-beta ASSUMED_BETA]
                      [--flux-cutoff FLUX_CUTOFF]
                      [--fwhm-scale-cutoff FWHM_SCALE_CUTOFF]
                      [--write-hyperdrive-model] [--write-calibrate-model]
                      [--write-ds9-region] [--holography-taper]
                      [--rotate-pa-to-phase-centre]
                      [--catalogue-path CATALOGUE_PATH]
                      [--catalogue-freq CATALOGUE_FREQ]
                      [--catalogue-freq-col CATALOGUE_FREQ_COL]
                      [--catalogue-freq-unit CATALOGUE_FREQ_UNIT]
                      [--catalogue-ra-col CATALOGUE_RA_COL]
                      [--catalogue-dec-col CATALOGUE_DEC_COL]
                      [--catalogue-flux-col CATALOGUE_FLUX_COL]
                      [--catalogue-name-col CATALOGUE_NAME_COL]
                      [--catalogue-maj-col CATALOGUE_MAJ_COL]
                      [--catalogue-min-col CATALOGUE_MIN_COL]
                      [--catalogue-pa-col CATALOGUE_PA_COL]
                      [--catalogue-sizes-deconvolved CATALOGUE_SIZES_DECONVOLVED]
                      [--catalogue-psf-maj-col CATALOGUE_PSF_MAJ_COL]
                      [--catalogue-psf-min-col CATALOGUE_PSF_MIN_COL]
                      [--catalogue-psf-pa-col CATALOGUE_PSF_PA_COL]
                      [--catalogue-alpha-col CATALOGUE_ALPHA_COL]
                      [--catalogue-beta-col CATALOGUE_BETA_COL]
                      [--catalogue-radec-unit CATALOGUE_RADEC_UNIT]
                      [--catalogue-flux-unit CATALOGUE_FLUX_UNIT]
                      [--catalogue-shape-unit CATALOGUE_SHAPE_UNIT]
                      ms

Positional Arguments¶

ms: Path to the measurement set to create the sky-model for

Named Arguments¶

--holofile: Holography cube to take the primary beam from. If unset, a Gaussian beam is used

Inputs for SkyModelOptions¶

--reference-catalogue-directory

The reference catalogue directory that contains the known flint reference catalogues

Default: .

--reference-name

--assumed-alpha

Assume this to be the typical spectral index if it is not recorded in the reference catalogue

Default: -0.83

--assumed-beta

Assume this to be the typical amount of spectral curvature should they not be in the reference catalogue

Default: 0.0

--flux-cutoff

The intrinsic brightness a source needs to be for it to be included in the sky model

Default: 0.02

--fwhm-scale-cutoff

A source needs to be within this many FWHM units from the direction of interest for it to be included

Default: 1

--write-hyperdrive-model

Should the model for hyperdrive be created. The output will have .hypderdrive.yaml suffix appended to the MS path.

Default: False

--write-calibrate-model

Should the model for calibrate be created. The output will have .calibrate.txt suffix appended to the MS path.

Default: False

--write-ds9-region

Should a DS9 region file be created. The output will have .ds9.reg suffix appended to the MS path.

Default: False

--holography-taper

Keep sources beyond the edge of the holography cube, continuing the beam past the edge as a Gaussian fall-off from the edge value. Off drops them, as linmos does.

Default: False

--rotate-pa-to-phase-centre

Measure position angles in the calibrate model from north at the phase centre, as addmodel expects, instead of from north at each source

Default: False

--catalogue-path

Path to a user-supplied catalogue file. If set, takes precedence over reference_catalogue_directory/reference_name. Column names/units below are never guessed.

--catalogue-freq

Reference frequency, in Hz, of catalogue_path’s flux column, used for every source. Ignored if catalogue_freq_col is set. One of catalogue_freq/catalogue_freq_col is required whenever catalogue_path is set.

--catalogue-freq-col

Per-source reference-frequency column in catalogue_path. If set, overrides catalogue_freq with a per-row value instead of one value for the whole catalogue.

--catalogue-freq-unit

Astropy unit string for catalogue_freq_col

Default: 'Hz'

--catalogue-ra-col

RA column in catalogue_path. Required whenever catalogue_path is set – never guessed

--catalogue-dec-col

Dec column in catalogue_path. Required whenever catalogue_path is set

--catalogue-flux-col

Flux column in catalogue_path. Required whenever catalogue_path is set

--catalogue-name-col

Source name column in catalogue_path. If unset, names are synthesised (src0, src1, …)

--catalogue-maj-col

Major-axis column in catalogue_path. None disables shape info (point sources). Must be set together with catalogue_min_col/catalogue_pa_col

--catalogue-min-col

Minor-axis column in catalogue_path, paired with catalogue_maj_col

--catalogue-pa-col

Position-angle column in catalogue_path, paired with catalogue_maj_col. Always degrees

--catalogue-sizes-deconvolved

Whether catalogue_maj_col/catalogue_min_col are already intrinsic (PSF-deconvolved) sizes, ready to use directly in the sky model, or as-observed (PSF-convolved) sizes that must be deconvolved first. Required whenever catalogue_maj_col is set – never guessed

--catalogue-psf-maj-col

Per-source PSF major-axis column in catalogue_path, used to deconvolve catalogue_maj_col/catalogue_min_col when catalogue_sizes_deconvolved is False. Required in that case – there is no pipeline restoring beam to fall back on here

--catalogue-psf-min-col

Per-source PSF minor-axis column, paired with catalogue_psf_maj_col

--catalogue-psf-pa-col

Per-source PSF position-angle column, paired with catalogue_psf_maj_col. Always degrees

--catalogue-alpha-col

Spectral index column in catalogue_path. If unset, falls back to assumed_alpha

--catalogue-beta-col

Spectral curvature column in catalogue_path. If unset, falls back to assumed_beta

--catalogue-radec-unit

Astropy unit string for catalogue_ra_col/catalogue_dec_col. Always applied explicitly, never inferred from the file

Default: 'deg'

--catalogue-flux-unit

Astropy unit string for catalogue_flux_col

Default: 'Jy'

--catalogue-shape-unit

Astropy unit string for catalogue_maj_col/catalogue_min_col/catalogue_psf_maj_col/catalogue_psf_min_col

Default: 'arcsec'

Sky-model calibration¶

Basic Overview¶

Fitting the spectral shape¶

Holography is not currently suupported¶

Output model types¶

calibrate and wsclean --save-source-list style¶

hyperdrive style¶

DS9 region file¶

Accessing via the CLI¶

Positional Arguments¶

Named Arguments¶

Inputs for SkyModelOptions¶

`calibrate` and `wsclean --save-source-list` style¶

`hyperdrive` style¶